APPENDIX ■ ■ ■ Quick Reference This 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 R^ r = gcnew R(); types on the garbage-collected (managed) heap generic Declares a parameterized type generic <typename T> ref class G { /* ... */ }; (generic) that is recognized by the runtime nullptr Evaluates to the null value for R^ r = nullptr; a pointer, indicating an unassigned pointer 355 356 APPENDIX ■ QUICK REFERENCE Table A-2. C++/CLI Contextual Keywords Contextual Description Usage Keyword abstract Declares a class that has some ref class Base abstract { /* ... */ }; 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. delegate Declares an object that represents delegate void MyDelegate(int); a type-safe function pointer. event Declares an event, an occurrence event EventHandler ClickEvent; that triggers method calls. finally Captures program flow after a finally { /* ... */ } try/catch block. in Used in the for each statement. for each (R^ r in collection) { /* ... */ } initonly Specifies a field that can only be initonly int i; modified in a constructor. internal Specifies that access to a member public ref class R is restricted to within an assembly. { internal: void f(); } literal Specifies a value that is a literal int SIZE = 150; literal constant. override Indicates that a function is intended virtual int f(int a, int b) override; to be a virtual override of the base class function of the same name. property Declares a field-like member property int P; on a type. sealed Indicates a type that cannot be used virtual int f(int a, int b) sealed; as a base class or a method cannot be overridden. where Used in the declaration of generics generic <typename T> where T : R to specify constraints on the types ref class G { /* ... */}; that may be used as type arguments for a generic type or function. 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. APPENDIX ■ QUICK REFERENCE 357 Table A-3. Whitespaced Keywords Whitespaced Description Usage Keyword enum class Declares an enumeration enum class Color { Red, Green, Blue}; with all members public enum struct Declares an enumeration enum struct Color { Red, Green, Blue }; with all members public for each Used to iterate over for each (R^ r in collection) { /* ... */ } collection classes interface class Declares an interface with interface class I { /* ... */ }; all members public interface struct Declares an interface with interface struct I { /* ... */ }; all members public ref class Declares a managed type ref class R { /* ... */ }; with private default accessibility ref struct Declares a managed ref struct S { /* ... */ }; struct with public default accessibility value class Declares a value type value class V { /* ... */ }; with private default accessibility value struct Declares a value type value struct S { /* ... */ }; with public default accessibility 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)++; 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. 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 360 APPENDIX ■ QUICK REFERENCE Table A-4. XML Doc Comment Reference (Continued) XML Tag Description <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 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) {} 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