Appendix A Quick Reference

355
■ ■ ■
APPENDIX
Quick Reference
T
his appendix covers the new keywords introduced in C++/CLI, specifies which are also reserved
words, and defines and lists contextual keywords and whitespaced keywords. This appendix
includes a reference table for features available in native, mixed, pure, and safe modes. You’ll
also find a summary of the syntax introduced in C++/CLI.
Keywords and Contextual Keywords
Some new keywords were introduced in the C++/CLI bindings. Many new keywords introduced
in C++/CLI are sensitive to the context in which they are used, so as to avoid creating new reserved
words in order not to interfere with existing identifiers. When used in the proper syntactic position,
contextual keywords are interpreted with the keyword meaning. When used in any other posi-
tion, they may be used as identifiers. This enables your code to continue to use a variable that
happens to collide with a C++/CLI contextual keyword without any special marking or modifi-
cation. This also enables C++/CLI to use keywords that otherwise would be common variable
names. There are several new keywords that are not contextual, as described in Table A-1: gcnew,
generic, and nullptr. Table A-2 shows the new contextual keywords.
Table A-1. C++/CLI Keywords
Keyword Description Usage
gcnew Allocates instances of reference
types on the garbage-collected
(managed) heap
R^ r = gcnew R();
generic Declares a parameterized type
(generic) that is recognized by
the runtime
generic <typename T> ref class G { /* ... */ };
nullptr Evaluates to the null value for
a pointer, indicating an

unassigned pointer
R^ r = nullptr;
Hogenson_705-2AppA.fm Page 355 Wednesday, October 18, 2006 5:16 PM
356
APPENDIX
■
QUICK REFERENCE
Whitespaced Keywords
Some of the keywords in C++/CLI are two words containing whitespace, which are referred to
as whitespaced keywords. For example, ref class is a whitespaced keyword. Spaces and tabs
may be used between the two words, but comments (despite technically being whitespace
after preprocessing) may not be used. Table A-3 lists the whitespaced keywords of C++/CLI.
Table A-2. C++/CLI Contextual Keywords
Contextual
Keyword
Description Usage
abstract Declares a class that has some
unimplemented methods, used as a
base class. Objects cannot be instan-
tiated from this class. When used on
a method, declares that the method
will not be implemented.
ref class Base abstract { /* ... */ };
delegate Declares an object that represents
a type-safe function pointer.
delegate void MyDelegate(int);
event Declares an event, an occurrence
that triggers method calls.
event EventHandler ClickEvent;
finally Captures program flow after a

try/catch block.
finally { /* ... */ }
in Used in the for each statement. for each (R^ r in collection)
{ /* ... */ }
initonly Specifies a field that can only be
modified in a constructor.
initonly int i;
internal Specifies that access to a member
is restricted to within an assembly.
public ref class R
{ internal: void f(); }
literal Specifies a value that is a
literal constant.
literal int SIZE = 150;
override Indicates that a function is intended
to be a virtual override of the base
class function of the same name.
virtual int f(int a, int b) override;
property Declares a field-like member
on a type.
property int P;
sealed Indicates a type that cannot be used
as a base class or a method cannot
be overridden.
virtual int f(int a, int b) sealed;
where Used in the declaration of generics
to specify constraints on the types
that may be used as type arguments
for a generic type or function.
generic <typename T> where T : R

ref class G { /* ... */};
Hogenson_705-2AppA.fm Page 356 Wednesday, October 18, 2006 5:16 PM
APPENDIX
■
QUICK REFERENCE
357
Keywords As Identifiers
You can specify __identifier to use a keyword as an identifier. Use it when you migrate
existing code to C++/CLI that uses one of the new keywords: gcnew, generic, or nullptr, or if
you are dealing with another code from another language that has an identifier that matches a
C++/CLI keyword, as in Listing A-1.
Listing A-1. Using __identifier
// identifier.cpp
using namespace System;
int main()
{
int __identifier(switch) = 10;
__identifier(switch)++;
Table A-3. Whitespaced Keywords
Whitespaced
Keyword
Description Usage
enum class Declares an enumeration
with all members public
enum class Color { Red, Green, Blue};
enum struct Declares an enumeration
with all members public
enum struct Color { Red, Green, Blue };
for each Used to iterate over
collection classes

for each (R^ r in collection) { /* ... */ }
interface class Declares an interface with
all members public
interface class I { /* ... */ };
interface struct Declares an interface with
all members public
interface struct I { /* ... */ };
ref class Declares a managed type
with private default
accessibility
ref class R { /* ... */ };
ref struct Declares a managed
struct with public
default accessibility
ref struct S { /* ... */ };
value class Declares a value type
with private default
accessibility
value class V { /* ... */ };
value struct Declares a value type
with public default
accessibility
value struct S { /* ... */ };
Hogenson_705-2AppA.fm Page 357 Wednesday, October 18, 2006 5:16 PM
358
APPENDIX
■
QUICK REFERENCE
switch( __identifier(switch) )
{

case 10:
break;
case 11:
Console::WriteLine("Switch is {0}", __identifier(switch));
break;
default:
break;
}
}
The output of Listing A-1 is as follows:
Switch is 11
The following sections describe features not otherwise covered in this book: how to detect
CLR compilation, and XML documentation comments.
Detecting CLR Compilation
Listing A-2 demonstrates how to detect CLR compilation.
Listing A-2. Detecting CLR Compilation
// detecting_clr.cpp
#include <stdio.h>
int main()
{
#ifdef _MANAGED
System::Console::WriteLine("Must be compiling with /clr...");
#else
printf("Not compiling with /clr.");
#endif
}
The output of Listing A-2 is as expected with or without the /clr option:
C:\code\appendix>cl /clr detecting_clr.cpp
Microsoft (R) C/C++ Optimizing Compiler Version 14.00.50727.42
for Microsoft (R) .NET Framework version 2.00.50727.42

Copyright (C) Microsoft Corporation. All rights reserved.
Hogenson_705-2AppA.fm Page 358 Wednesday, October 18, 2006 5:16 PM
APPENDIX
■
QUICK REFERENCE
359
detecting_clr.cpp
Microsoft (R) Incremental Linker Version 8.00.50727.42
Copyright (C) Microsoft Corporation. All rights reserved.
/out:detecting_clr.exe
detecting_clr.obj
C:\code\appendix>detecting_clr
Must be compiling with /clr...
C:\ code\appendix>cl detecting_clr.cpp
Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 14.00.50727.42 for 80x86
Copyright (C) Microsoft Corporation. All rights reserved.
detecting_clr.cpp
Microsoft (R) Incremental Linker Version 8.00.50727.42
Copyright (C) Microsoft Corporation. All rights reserved.
/out:detecting_clr.exe
detecting_clr.obj
C:\ code\appendix>detecting_clr
Not compiling with /clr.
XML Documentation
XML files may be generated from code comments written in the CLR XML doc format by writing
comments in the format in code and compiling with the /doc compiler option. You can use
these XML files to generate formatted documentation. The tool xdcmake.exe is used to generate
the XML files from doc comments. Table A-4 lists the XML tags available.
Table A-4. XML Doc Comment Reference
XML Tag Description

<c>inline code</c> Inline code
<code>code block</c> Lines of code
<example>example section</example> Defines a section containing text
description and an optional code
example
<exception cref="member">description</exception> Specifies exceptions that may
be generated
<include file="filename" path="tagpath"> Includes XML comments from a file
<list> Defines a bulleted or numbered list
or table
Hogenson_705-2AppA.fm Page 359 Wednesday, October 18, 2006 5:16 PM
360
APPENDIX
■
QUICK REFERENCE
Listing A-3 illustrates the use of the XML comment format and the generation of XML
documentation from the comments.
Listing A-3. Using XML Documentation
// xml_comments.cpp
// compile with: /LD /clr /doc
// then run: xdcmake xml_comments.xdc
using namespace System;
/// Ref class R demonstrates XML Documentation Comments.
/// <summary> A class demonstrating documentation comments </summary>
/// <remarks> A detailed description of R goes into the remarks block
/// </remarks>
public ref class R
{
public:
/// <summary>F is a method in the R class.

/// <para>You can break the comments into paragraphs.
/// <see cref="R::G"/> for related information.</para>
/// <seealso cref="R::G"/>
/// </summary>
void F(int i) {}
<para>text</para> Defines a paragraph
<param>description</param> Describes a function parameter
<paramref name="name"> Specifies a hyperlink to
the parameter
<permission cref="member"> Specifies access (e.g., public)
<remarks>description</remarks> Specifies the detailed description
<returns>description</returns> Specifies the return
value information
<see cref="member"> Specifies a cross-reference
<seealso cref="member"> Lists additional references
<summary>text</summary> Specifies text that gives a
brief synopsis
<value>description</value> Specifies a property description
Table A-4. XML Doc Comment Reference (Continued)
XML Tag Description
Hogenson_705-2AppA.fm Page 360 Wednesday, October 18, 2006 5:16 PM
APPENDIX
■
QUICK REFERENCE
361
/// The method G is a method in the R class.
/// <summary>Counts the number of characters in two strings.</summary>
/// <param name="s1"> Description for s1</param>
/// <param name="s2"> Description for s2</param>
/// <returns>The sum of the length of two strings.</returns>

int G(String^ s1, String^ s2){ return s1->Length + s2->Length; }
};
Listing A-3 is compiled with
cl /clr /doc /LD xml_comments.cpp
The documentation comments are generated with
xdcmake xml_comments.xdc
The resulting xml_comments.xml file, with some minor whitespace alterations, is as follows:
<?xml version="1.0"?>
<doc>
<assembly>
xml_comments
</assembly>
<members>
<member name="M:R.G(System.String,System.String)">
The method G is a method in the R class.
<summary>Counts the number of characters in two strings.
</summary>
<param name="s1"> Description for s1</param>
<param name="s2"> Description for s2</param>
<returns>The sum of the length of two strings.</returns>
</member>
<member name="M:R.F(System.Int32)">
<summary>F is a method in the R class.
<para>You can break the comments into paragraphs.
<see cref="M:R.G(System.String,System.String)" />
for related information.
</para>
<seealso cref="M:R.G(System.String,System.String)" />
</summary>
</member>

<member name="T:R">
Ref class R demonstrates XML Documentation Comments.
<summary> A class demonstrating documentation comments </summary>
<remarks> A detailed description of R goes into the remarks block
</remarks>
</member>
</members>
</doc>
Hogenson_705-2AppA.fm Page 361 Wednesday, October 18, 2006 5:16 PM
362
APPENDIX
■
QUICK REFERENCE
It is up to you to then render this in the desired user-friendly documentation format. For
example, you could generate documentation in various formats using a tool such as Sandcastle,
available from the Microsoft download center ( />Summary of Compilation Modes
This book has covered many aspects of the various modes, but not all. Table A-5 summarizes
the features available in each compilation mode.
Table A-5. Features Available in Various Compilation Modes
Feature Native Mixed Pure Safe
Define and use native types Yes Yes Yes No
Define and use managed types No Yes Yes Yes
Define native functions Yes Yes No No
Define managed functions No Yes Yes Yes
Native instructions* Yes Yes No No
Managed instructions (IL) No Yes Yes Yes
Build 32-/64-bit
agnostic assemblies
No No No Yes
Use the NET Framework No Yes Yes Yes

Use the CRT Yes Yes MSIL CRT No
Use the Standard C++ Library Yes Yes MSIL version No
Use ATL Yes Yes No No
Use MFC Yes Yes No No
App domain aware No No Yes Yes
Reflection on built assembly No DLLs only Yes Yes
Call functions via P/Invoke N/A Yes Yes Yes
Use unsafe casts** Yes Yes Yes No
Include native header Yes Yes Depends
on header
No
Include managed header No Yes Yes Yes
#using managed assembly No Yes Yes Yes
#import COM typelib/DLL Yes Yes No No
Compile C code Yes No No No
Floating-point control
(__controlfp, etc)
Yes No No No
std::set_terminate and SIGTERM Yes No No No
Hogenson_705-2AppA.fm Page 362 Wednesday, October 18, 2006 5:16 PM