From ab8b9404cbd2bbaff514e8b21ec1f9b6e3c310ed Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Fri, 26 Jan 2024 10:54:05 -0800 Subject: [PATCH 01/14] explain switch options --- docs/cpp/tutorial-import-stl-named-module.md | 40 +++++++++++--------- 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/docs/cpp/tutorial-import-stl-named-module.md b/docs/cpp/tutorial-import-stl-named-module.md index 791dc43e7e6..e59ad47a108 100644 --- a/docs/cpp/tutorial-import-stl-named-module.md +++ b/docs/cpp/tutorial-import-stl-named-module.md @@ -1,6 +1,6 @@ --- title: "Tutorial: Import the standard library (STL) using modules from the command line (C++)" -ms.date: 06/08/2023 +ms.date: 01/26/2024 ms.topic: "tutorial" author: "tylermsft" ms.author: "twhitney" @@ -58,16 +58,16 @@ The statement `import std;` or `import std.compat;` imports the standard library ### Example: `std` 1. Open a x86 Native Tools Command Prompt for VS: from the Windows **Start** menu, type *x86 native* and the prompt should appear in the list of apps. Ensure that the prompt is for Visual Studio 2022 preview version 17.5 or above. You'll get errors if you use the wrong version of the prompt. The examples used in this tutorial are for the CMD shell. If you use PowerShell, use `"$Env:VCToolsInstallDir\modules\std.ixx"` instead of `"%VCToolsInstallDir\modules\std.ixx"`. -1. Create a directory, such as `%USERPROFILE%\source\repos\STLModules`, and make it the current directory. If you choose a directory that you don't have write access to, you'll get errors such as not being able to open the output file `std.ifc`. +1. Create a directory, such as `%USERPROFILE%\source\repos\STLModules`, and make it the current directory. If you choose a directory that you don't have write access to, you'll get errors during compilation such as not being able to open the output file `std.ifc`. 1. Compile the `std` named module with the following command: - ```dos - cl /std:c++latest /EHsc /nologo /W4 /MTd /c "%VCToolsInstallDir%\modules\std.ixx" + ```cmd + cl /c /nologo /std:c++latest /EHsc /W4 "%VCToolsInstallDir%\modules\std.ixx" ``` If you get errors, ensure that you're using the correct version of the command prompt. If you're still having issues, please file a bug at [Visual Studio Developer Community](https://developercommunity.visualstudio.com/home). - You should compile the `std` named module using the same compiler settings that you intend to use with the code that imports it. If you have a multi-project solution, you can compile the standard library named module once, and then refer to it from all of your projects by using the [`/reference`](../build/reference/module-reference.md) compiler option. + Compile the `std` named module using the same compiler settings that you intend to use with the code that imports it. If you have a multi-project solution, you can compile the standard library named module once, and then refer to it from all of your projects by using the [`/reference`](../build/reference/module-reference.md) compiler option. Using the previous compiler command, the compiler outputs two files: - `std.ifc` is the compiled binary representation of the named module interface that the compiler consults to process the `import std;` statement. This is a compile-time only artifact. It doesn't ship with your application. @@ -77,12 +77,16 @@ The statement `import std;` or `import std.compat;` imports the standard library | Switch | Meaning | |---|---| + | [`/c`](../build/reference/c-compile-without-linking.md) | Compile without linking, because we are just building the binary named module interface at this point. | | [`/std:c++:latest`](../build/reference/std-specify-language-standard-version.md) | Use the latest version of the C++ language standard and library. Although module support is available under `/std:c++20`, you need the latest standard library to get support for standard library named modules. | | [`/EHsc`](../build/reference/eh-exception-handling-model.md) | Use C++ exception handling, except for functions marked `extern "C"`. | - | [`/MTd`](../build/reference/md-mt-ld-use-run-time-library.md) | Use the static multithreaded debug run-time library. | - | [`/c`](../build/reference/c-compile-without-linking.md) | Compile without linking. | + | [`/W4`](../build/reference/w4-enable-all-warnings.md) | Enable all warnings. | + + As an aside, you can control the object file name and the named module interface file name with the following switches: + - [`/Fo`](../build/reference/fo-object-file-name.md). For example, `/Fo "somethingelse.obj"`. By default, the compiler creates a file name that is the same as the module name you are compiling. In the example, the output name is `std.obj` because we are compiling the file `std.ixx`. + - [`/ifcOutput`](../build/reference/ifcoutput-named-module-interface-file-name.md). For example, `/ifcOutput "somethingelse.ifc"`. In the example, the generated `ifc` file is `std.ifc` because we are compiling the file `std.ixx`. -1. To try out importing the `std` library, start by creating a file named `importExample.cpp` with the following content: +1. Try out importing the `std` library by creating a file named `importExample.cpp` with the following content: ```cpp // requires /std:c++latest @@ -104,16 +108,16 @@ The statement `import std;` or `import std.compat;` imports the standard library 1. Compile the example by using the following command in the same directory as the previous step: - ```dos - cl /std:c++latest /EHsc /nologo /W4 /MTd importExample.cpp std.obj + ```cmd + cl /std:c++latest /EHsc /nologo /W4 /reference "std=std.ifc" importExample.cpp std.obj ``` - We didn't have to specify `std.ifc` on the command line because the compiler automatically looks for the `.ifc` file matching the module name specified by the `import` statement. When the compiler encounters `import std;`, it finds `std.ifc` since we put it in the same directory as the source code--relieving us of the need to specify it on the command line. If the `.ifc` file is in a different directory than the source code, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. + It isn't necessary to specify `/reference "std=std.ifc"` on the command line in this example because the compiler automatically looks for the `.ifc` file matching the module name specified by the `import` statement. When the compiler encounters `import std;`, it can find `std.ifc` if it is located in the same directory as the source code. If the `.ifc` file is in a different directory than the source code, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. If you're building a single project, you can combine the steps of building the `std` standard library named module and the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` to the command line. Make sure to put it before any `.cpp` files that consume it. By default, the output executable's name is taken from the first input file. Use the `/Fe` compiler option to specify the output file name you want. This tutorial shows compiling the `std` named module as a separate step because you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects. But it may be convenient to build everything together, as shown by this command line: - ```dos - cl /FeimportExample /std:c++latest /EHsc /nologo /W4 /MTd "%VCToolsInstallDir%\modules\std.ixx" importExample.cpp + ```cmd + cl /FeimportExample /std:c++latest /EHsc /nologo /W4 "%VCToolsInstallDir%\modules\std.ixx" importExample.cpp ``` Given the previous command line, the compiler produces an executable named `importExample.exe`. When you run it, it produces the following output: @@ -139,8 +143,8 @@ Before you can use `import std.compat;` you must compile the module interface fi 1. Create a directory to try this example, such as `%USERPROFILE%\source\repos\STLModules`, and make it the current directory. If you choose a directory that you don't have write access to, you'll get errors such as not being able to open the output file `std.ifc`. 1. Compile the `std` and `std.compat` named modules with the following command: - ```dos - cl /std:c++latest /EHsc /nologo /W4 /MTd /c "%VCToolsInstallDir%\modules\std.ixx" "%VCToolsInstallDir%\modules\std.compat.ixx" + ```cmd + cl /std:c++latest /EHsc /nologo /W4 /c "%VCToolsInstallDir%\modules\std.ixx" "%VCToolsInstallDir%\modules\std.compat.ixx" ``` You should compile `std` and `std.compat` using the same compiler settings that you intend to use with the code that imports them. If you have a multi-project solution, you can compile them once, and then refer to them from all of your projects using the [`/reference`](../build/reference/module-reference.md) compiler option. @@ -175,7 +179,7 @@ Before you can use `import std.compat;` you must compile the module interface fi 1. Compile the example by using the following command: ```cmd - cl /std:c++latest /EHsc /nologo /W4 /MTd stdCompatExample.cpp std.obj std.compat.obj + cl /std:c++latest /EHsc /nologo /W4 stdCompatExample.cpp std.obj std.compat.obj ``` We didn't have to specify `std.compat.ifc` on the command line because the compiler automatically looks for the `.ifc` file that matches the module name in an `import` statement. When the compiler encounters `import std.compat;` it finds `std.compat.ifc` since we put it in the same directory as the source code--relieving us of the need to specify it on the command line. If the `.ifc` file is in a different directory than the source code, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. @@ -184,8 +188,8 @@ Before you can use `import std.compat;` you must compile the module interface fi If you're building a single project, you can combine the step of building the `std` and `std.compat` standard library named modules with the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` and `"%VCToolsInstallDir%\modules\std.compat.ixx"` (in that order) to the command line. Make sure to put them before any `.cpp` files that consume them, and specify `/Fe` to name the built `exe` as shown in this example: - ```dos - cl /FestdCompatExample /std:c++latest /EHsc /nologo /W4 /MTd "%VCToolsInstallDir%\modules\std.ixx" "%VCToolsInstallDir%\modules\std.compat.ixx" stdCompatExample.cpp + ```cmd + cl /FestdCompatExample /std:c++latest /EHsc /nologo /W4 "%VCToolsInstallDir%\modules\std.ixx" "%VCToolsInstallDir%\modules\std.compat.ixx" stdCompatExample.cpp ``` I've shown them as separate steps in this tutorial because you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects. But it may be convenient to build them all at once. From 345486313146caea9288e41a2695bd419ab2ea18 Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Fri, 26 Jan 2024 11:01:58 -0800 Subject: [PATCH 02/14] tidy --- docs/cpp/tutorial-import-stl-named-module.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/cpp/tutorial-import-stl-named-module.md b/docs/cpp/tutorial-import-stl-named-module.md index e59ad47a108..92c48465a44 100644 --- a/docs/cpp/tutorial-import-stl-named-module.md +++ b/docs/cpp/tutorial-import-stl-named-module.md @@ -62,7 +62,7 @@ The statement `import std;` or `import std.compat;` imports the standard library 1. Compile the `std` named module with the following command: ```cmd - cl /c /nologo /std:c++latest /EHsc /W4 "%VCToolsInstallDir%\modules\std.ixx" + cl /std:c++latest /EHsc /c /nologo /W4 /c "%VCToolsInstallDir%\modules\std.ixx" ``` If you get errors, ensure that you're using the correct version of the command prompt. If you're still having issues, please file a bug at [Visual Studio Developer Community](https://developercommunity.visualstudio.com/home). @@ -80,13 +80,13 @@ The statement `import std;` or `import std.compat;` imports the standard library | [`/c`](../build/reference/c-compile-without-linking.md) | Compile without linking, because we are just building the binary named module interface at this point. | | [`/std:c++:latest`](../build/reference/std-specify-language-standard-version.md) | Use the latest version of the C++ language standard and library. Although module support is available under `/std:c++20`, you need the latest standard library to get support for standard library named modules. | | [`/EHsc`](../build/reference/eh-exception-handling-model.md) | Use C++ exception handling, except for functions marked `extern "C"`. | - | [`/W4`](../build/reference/w4-enable-all-warnings.md) | Enable all warnings. | + | [`/W4`](../build/reference/w4-enable-all-warnings.md) | Using /W4 is generally recommended, especially for new projects because it enables all level 1, level 2, level 3, and most level 4 (informational) warnings, which can help you catch potential issues early. It essentially provides lint-like warnings that can help ensure the fewest possible hard-to-find code defects. | - As an aside, you can control the object file name and the named module interface file name with the following switches: + You can control the object file name and the named module interface file name with the following switches: - [`/Fo`](../build/reference/fo-object-file-name.md). For example, `/Fo "somethingelse.obj"`. By default, the compiler creates a file name that is the same as the module name you are compiling. In the example, the output name is `std.obj` because we are compiling the file `std.ixx`. - [`/ifcOutput`](../build/reference/ifcoutput-named-module-interface-file-name.md). For example, `/ifcOutput "somethingelse.ifc"`. In the example, the generated `ifc` file is `std.ifc` because we are compiling the file `std.ixx`. -1. Try out importing the `std` library by creating a file named `importExample.cpp` with the following content: +1. Try importing the `std` library by creating a file named `importExample.cpp` with the following content: ```cpp // requires /std:c++latest From 7b934913ab2e059bc32769da07daf8b5e5468849 Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Fri, 26 Jan 2024 11:09:39 -0800 Subject: [PATCH 03/14] reorder explanation of switches to match command line --- docs/cpp/tutorial-import-stl-named-module.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/cpp/tutorial-import-stl-named-module.md b/docs/cpp/tutorial-import-stl-named-module.md index 92c48465a44..aa7c0ae0011 100644 --- a/docs/cpp/tutorial-import-stl-named-module.md +++ b/docs/cpp/tutorial-import-stl-named-module.md @@ -77,12 +77,12 @@ The statement `import std;` or `import std.compat;` imports the standard library | Switch | Meaning | |---|---| - | [`/c`](../build/reference/c-compile-without-linking.md) | Compile without linking, because we are just building the binary named module interface at this point. | | [`/std:c++:latest`](../build/reference/std-specify-language-standard-version.md) | Use the latest version of the C++ language standard and library. Although module support is available under `/std:c++20`, you need the latest standard library to get support for standard library named modules. | | [`/EHsc`](../build/reference/eh-exception-handling-model.md) | Use C++ exception handling, except for functions marked `extern "C"`. | + | [`/c`](../build/reference/c-compile-without-linking.md) | Compile without linking, because we are just building the binary named module interface at this point. | | [`/W4`](../build/reference/w4-enable-all-warnings.md) | Using /W4 is generally recommended, especially for new projects because it enables all level 1, level 2, level 3, and most level 4 (informational) warnings, which can help you catch potential issues early. It essentially provides lint-like warnings that can help ensure the fewest possible hard-to-find code defects. | - You can control the object file name and the named module interface file name with the following switches: + If your build scenario requires it, you can control the object file name and the named module interface file name with the following switches: - [`/Fo`](../build/reference/fo-object-file-name.md). For example, `/Fo "somethingelse.obj"`. By default, the compiler creates a file name that is the same as the module name you are compiling. In the example, the output name is `std.obj` because we are compiling the file `std.ixx`. - [`/ifcOutput`](../build/reference/ifcoutput-named-module-interface-file-name.md). For example, `/ifcOutput "somethingelse.ifc"`. In the example, the generated `ifc` file is `std.ifc` because we are compiling the file `std.ixx`. From ab6741b65f8d3155d2ab3b4aff7a447d9d107aab Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Fri, 26 Jan 2024 11:19:36 -0800 Subject: [PATCH 04/14] break compile/link into 2 steps --- docs/cpp/tutorial-import-stl-named-module.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/cpp/tutorial-import-stl-named-module.md b/docs/cpp/tutorial-import-stl-named-module.md index aa7c0ae0011..d9239599689 100644 --- a/docs/cpp/tutorial-import-stl-named-module.md +++ b/docs/cpp/tutorial-import-stl-named-module.md @@ -109,11 +109,14 @@ The statement `import std;` or `import std.compat;` imports the standard library 1. Compile the example by using the following command in the same directory as the previous step: ```cmd - cl /std:c++latest /EHsc /nologo /W4 /reference "std=std.ifc" importExample.cpp std.obj + cl /c /std:c++latest /EHsc /nologo /W4 /reference "std=std.ifc" importExample.cpp + link importExample.obj std.obj ``` It isn't necessary to specify `/reference "std=std.ifc"` on the command line in this example because the compiler automatically looks for the `.ifc` file matching the module name specified by the `import` statement. When the compiler encounters `import std;`, it can find `std.ifc` if it is located in the same directory as the source code. If the `.ifc` file is in a different directory than the source code, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. + In this example, compiling your source code and linking the module's implementation into your application are separate steps. They don't have to be. You could have used `cl /std:c++latest /EHsc /nologo /W4 /reference "std=std.ifc" importExample.cpp std.obj` to compile and link in one step. But it may be convenient to build and link separately. For example, you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects. + If you're building a single project, you can combine the steps of building the `std` standard library named module and the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` to the command line. Make sure to put it before any `.cpp` files that consume it. By default, the output executable's name is taken from the first input file. Use the `/Fe` compiler option to specify the output file name you want. This tutorial shows compiling the `std` named module as a separate step because you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects. But it may be convenient to build everything together, as shown by this command line: ```cmd From 8a284af34473e1dccd76cdee6447f67b4ba7edc1 Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Fri, 26 Jan 2024 11:28:55 -0800 Subject: [PATCH 05/14] fix links --- docs/cpp/tutorial-import-stl-named-module.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/cpp/tutorial-import-stl-named-module.md b/docs/cpp/tutorial-import-stl-named-module.md index d9239599689..0806858a722 100644 --- a/docs/cpp/tutorial-import-stl-named-module.md +++ b/docs/cpp/tutorial-import-stl-named-module.md @@ -62,7 +62,7 @@ The statement `import std;` or `import std.compat;` imports the standard library 1. Compile the `std` named module with the following command: ```cmd - cl /std:c++latest /EHsc /c /nologo /W4 /c "%VCToolsInstallDir%\modules\std.ixx" + cl /std:c++latest /EHsc /nologo /W4 /c "%VCToolsInstallDir%\modules\std.ixx" ``` If you get errors, ensure that you're using the correct version of the command prompt. If you're still having issues, please file a bug at [Visual Studio Developer Community](https://developercommunity.visualstudio.com/home). @@ -79,14 +79,14 @@ The statement `import std;` or `import std.compat;` imports the standard library |---|---| | [`/std:c++:latest`](../build/reference/std-specify-language-standard-version.md) | Use the latest version of the C++ language standard and library. Although module support is available under `/std:c++20`, you need the latest standard library to get support for standard library named modules. | | [`/EHsc`](../build/reference/eh-exception-handling-model.md) | Use C++ exception handling, except for functions marked `extern "C"`. | - | [`/c`](../build/reference/c-compile-without-linking.md) | Compile without linking, because we are just building the binary named module interface at this point. | - | [`/W4`](../build/reference/w4-enable-all-warnings.md) | Using /W4 is generally recommended, especially for new projects because it enables all level 1, level 2, level 3, and most level 4 (informational) warnings, which can help you catch potential issues early. It essentially provides lint-like warnings that can help ensure the fewest possible hard-to-find code defects. | + | [`/W4`](../build/reference//compiler-option-warning-level.md) | Using /W4 is generally recommended, especially for new projects because it enables all level 1, level 2, level 3, and most level 4 (informational) warnings, which can help you catch potential issues early. It essentially provides lint-like warnings that can help ensure the fewest possible hard-to-find code defects. | + | [`/c`](../build/reference/c-compile-without-linking.md) | Compile without linking, because we're just building the binary named module interface at this point. | - If your build scenario requires it, you can control the object file name and the named module interface file name with the following switches: - - [`/Fo`](../build/reference/fo-object-file-name.md). For example, `/Fo "somethingelse.obj"`. By default, the compiler creates a file name that is the same as the module name you are compiling. In the example, the output name is `std.obj` because we are compiling the file `std.ixx`. - - [`/ifcOutput`](../build/reference/ifcoutput-named-module-interface-file-name.md). For example, `/ifcOutput "somethingelse.ifc"`. In the example, the generated `ifc` file is `std.ifc` because we are compiling the file `std.ixx`. + You can control the object file name and the named module interface file name with the following switches: + - [`/Fo`](../build/reference/fo-object-file-name.md). For example, `/Fo "somethingelse.obj"`. By default, the compiler creates a file name that is the same as the module name you are compiling. In the example, the output name is `std.obj` because we're compiling the file `std.ixx`. + - [`/ifcOutput`](../build/reference/ifc-output.md). For example, `/ifcOutput "somethingelse.ifc"`. In the example, the generated `ifc` file is `std.ifc` because we're compiling the file `std.ixx`. -1. Try importing the `std` library by creating a file named `importExample.cpp` with the following content: +1. Importing the `std` library you just built by creating a file named `importExample.cpp` with the following content: ```cpp // requires /std:c++latest From d139209d4b23595cb541220c645a0083f110d73d Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Fri, 26 Jan 2024 11:31:16 -0800 Subject: [PATCH 06/14] language cleanup --- docs/cpp/tutorial-import-stl-named-module.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cpp/tutorial-import-stl-named-module.md b/docs/cpp/tutorial-import-stl-named-module.md index 0806858a722..7ac8061f453 100644 --- a/docs/cpp/tutorial-import-stl-named-module.md +++ b/docs/cpp/tutorial-import-stl-named-module.md @@ -115,7 +115,7 @@ The statement `import std;` or `import std.compat;` imports the standard library It isn't necessary to specify `/reference "std=std.ifc"` on the command line in this example because the compiler automatically looks for the `.ifc` file matching the module name specified by the `import` statement. When the compiler encounters `import std;`, it can find `std.ifc` if it is located in the same directory as the source code. If the `.ifc` file is in a different directory than the source code, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. - In this example, compiling your source code and linking the module's implementation into your application are separate steps. They don't have to be. You could have used `cl /std:c++latest /EHsc /nologo /W4 /reference "std=std.ifc" importExample.cpp std.obj` to compile and link in one step. But it may be convenient to build and link separately. For example, you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects. + In this example, compiling your source code and linking the module's implementation into your application are separate steps. They don't have to be. You could have used `cl /std:c++latest /EHsc /nologo /W4 /reference "std=std.ifc" importExample.cpp std.obj` to compile and link in one step. But it may be convenient to build and link separately because then you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects, in your build's link step. If you're building a single project, you can combine the steps of building the `std` standard library named module and the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` to the command line. Make sure to put it before any `.cpp` files that consume it. By default, the output executable's name is taken from the first input file. Use the `/Fe` compiler option to specify the output file name you want. This tutorial shows compiling the `std` named module as a separate step because you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects. But it may be convenient to build everything together, as shown by this command line: From 2968e89a1ee5cade11f6a783eec6df642cd83c86 Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Fri, 26 Jan 2024 14:49:09 -0800 Subject: [PATCH 07/14] github 4158 --- docs/atl-mfc-shared/reference/csimplestringt-class.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/atl-mfc-shared/reference/csimplestringt-class.md b/docs/atl-mfc-shared/reference/csimplestringt-class.md index 98a3d829467..cfc4bffc408 100644 --- a/docs/atl-mfc-shared/reference/csimplestringt-class.md +++ b/docs/atl-mfc-shared/reference/csimplestringt-class.md @@ -1,7 +1,7 @@ --- description: "Learn more about: CSimpleStringT Class" title: "CSimpleStringT Class" -ms.date: 10/04/2021 +ms.date: 01/26/2024 f1_keywords: ["CSimpleStringT", "ATLSIMPSTR/ATL::CSimpleStringT", "ATLSIMPSTR/ATL::CSimpleStringT::PCXSTR", "ATLSIMPSTR/ATL::CSimpleStringT::PXSTR", "ATLSIMPSTR/ATL::CSimpleStringT::CSimpleStringT", "ATLSIMPSTR/ATL::CSimpleStringT::Append", "ATLSIMPSTR/ATL::CSimpleStringT::AppendChar", "ATLSIMPSTR/ATL::CSimpleStringT::CopyChars", "ATLSIMPSTR/ATL::CSimpleStringT::CopyCharsOverlapped", "ATLSIMPSTR/ATL::CSimpleStringT::Empty", "ATLSIMPSTR/ATL::CSimpleStringT::FreeExtra", "ATLSIMPSTR/ATL::CSimpleStringT::GetAllocLength", "ATLSIMPSTR/ATL::CSimpleStringT::GetAt", "ATLSIMPSTR/ATL::CSimpleStringT::GetBuffer", "ATLSIMPSTR/ATL::CSimpleStringT::GetBufferSetLength", "ATLSIMPSTR/ATL::CSimpleStringT::GetLength", "ATLSIMPSTR/ATL::CSimpleStringT::GetManager", "ATLSIMPSTR/ATL::CSimpleStringT::GetString", "ATLSIMPSTR/ATL::CSimpleStringT::IsEmpty", "ATLSIMPSTR/ATL::CSimpleStringT::LockBuffer", "ATLSIMPSTR/ATL::CSimpleStringT::Preallocate", "ATLSIMPSTR/ATL::CSimpleStringT::ReleaseBuffer", "ATLSIMPSTR/ATL::CSimpleStringT::ReleaseBufferSetLength", "ATLSIMPSTR/ATL::CSimpleStringT::SetAt", "ATLSIMPSTR/ATL::CSimpleStringT::SetManager", "ATLSIMPSTR/ATL::CSimpleStringT::SetString", "ATLSIMPSTR/ATL::CSimpleStringT::StringLength", "ATLSIMPSTR/ATL::CSimpleStringT::Truncate", "ATLSIMPSTR/ATL::CSimpleStringT::UnlockBuffer"] helpviewer_keywords: ["shared classes, CSimpleStringT", "strings [C++], ATL class", "CSimpleStringT class"] --- @@ -445,7 +445,7 @@ An `PXSTR` pointer to the object's (null-terminated) character buffer. Call this method to return the buffer contents of the `CSimpleStringT` object. The returned `PXSTR` is not a constant and therefore allows direct modification of `CSimpleStringT` contents. -If you use the pointer returned by `GetBuffer` to change the string contents, you must call [`ReleaseBuffer`](#releasebuffer) before you use any other `CSimpleStringT` member methods. +If you use the pointer returned by `GetBuffer` to change the string contents, you must call [`ReleaseBuffer`](#releasebuffer) to update the internal state of `CSimpleStringT` before you use any other `CSimpleStringT` methods. The address returned by `GetBuffer` may not be valid after the call to `ReleaseBuffer` because additional `CSimpleStringT` operations can cause the `CSimpleStringT` buffer to be reallocated. The buffer is not reallocated if you do not change the length of the `CSimpleStringT`. @@ -491,7 +491,7 @@ A `PXSTR` pointer to the object's (null-terminated) character buffer. Call this method to retrieve a specified length of the internal buffer of the `CSimpleStringT` object. The returned `PXSTR` pointer is not **`const`** and thus allows direct modification of `CSimpleStringT` contents. -If you use the pointer returned by [`GetBufferSetLength`](#getbuffersetlength) to change the string contents, call `ReleaseBuffer` to update the internal state of `CsimpleStringT` before you use any other `CSimpleStringT` methods. +If you use the pointer returned by [`GetBufferSetLength`](#getbuffersetlength) to change the string contents, call `ReleaseBuffer` to update the internal state of `CSimpleStringT` before you use any other `CSimpleStringT` methods. The address returned by `GetBufferSetLength` may not be valid after the call to `ReleaseBuffer` because additional `CSimpleStringT` operations can cause the `CSimpleStringT` buffer to be reallocated. The buffer is not reassigned if you do not change the length of the `CSimpleStringT`. @@ -502,9 +502,7 @@ If you keep track of the string length yourself, do not append the terminating n For more information about reference counting, see the following articles: - [Managing Object Lifetimes through Reference Counting](/windows/win32/com/managing-object-lifetimes-through-reference-counting) in the Windows SDK. - - [Implementing Reference Counting](/windows/win32/com/implementing-reference-counting) in the Windows SDK. - - [Rules for Managing Reference Counts](/windows/win32/com/rules-for-managing-reference-counts) in the Windows SDK. ### Example @@ -520,6 +518,8 @@ pstr[2] = _T('p'); // No need for trailing zero or call to ReleaseBuffer() // because GetBufferSetLength() set it for us. +// If we had called GetBuffer() instead of GetBufferSetLength() +// then we would have needed to call ReleaseBuffer(). str += _T(" soccer is best!"); ASSERT(_tcscmp(str, _T("Cup soccer is best!")) == 0); From 1443bc932e5ffb3157a7bbfe4481385eb405e53e Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Fri, 26 Jan 2024 15:09:33 -0800 Subject: [PATCH 08/14] add notes about renaming output to the std.compat example --- docs/cpp/tutorial-import-stl-named-module.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/cpp/tutorial-import-stl-named-module.md b/docs/cpp/tutorial-import-stl-named-module.md index 7ac8061f453..5a95f3ec772 100644 --- a/docs/cpp/tutorial-import-stl-named-module.md +++ b/docs/cpp/tutorial-import-stl-named-module.md @@ -83,8 +83,8 @@ The statement `import std;` or `import std.compat;` imports the standard library | [`/c`](../build/reference/c-compile-without-linking.md) | Compile without linking, because we're just building the binary named module interface at this point. | You can control the object file name and the named module interface file name with the following switches: - - [`/Fo`](../build/reference/fo-object-file-name.md). For example, `/Fo "somethingelse.obj"`. By default, the compiler creates a file name that is the same as the module name you are compiling. In the example, the output name is `std.obj` because we're compiling the file `std.ixx`. - - [`/ifcOutput`](../build/reference/ifc-output.md). For example, `/ifcOutput "somethingelse.ifc"`. In the example, the generated `ifc` file is `std.ifc` because we're compiling the file `std.ixx`. + - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo "somethingelse.obj"`. By default, the compiler uses the same name as the module source file (`.ixx`) you are compiling. In the example, the output name is `std.obj` by default because we're compiling the module file `std.ixx`. + - [`/ifcOutput`](../build/reference/ifc-output.md) sets the name of the named module interface file (`.ifc`). For example, `/ifcOutput "somethingelse.ifc"`. By default, the compiler uses the same name as the module source file (`.ixx`) you are compiling. In the example, the generated `ifc` file is `std.ifc` by default because we're compiling the module file `std.ixx`. 1. Importing the `std` library you just built by creating a file named `importExample.cpp` with the following content: @@ -159,6 +159,10 @@ Before you can use `import std.compat;` you must compile the module interface fi - `std.obj` contains the implementation of the standard library. - `std.compat.ifc` is the compiled binary named module interface that the compiler consults to process the `import std.compat;` statement. This is a compile-time only artifact. It doesn't ship with your application. - `std.compat.obj` contains implementation. However, most of the implementation is provided by `std.obj`. Add `std.obj` to the command line when you compile the sample app to statically link the functionality that you use from the standard library into your application. + - + As before in the `std` example, you can control the object file name and the named module interface file name with the following switches: + - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo "somethingelse.obj"`. By default, the compiler uses the same name as the module source file (`.ixx`) you are compiling. In the example, the output names are `std.obj` and `std.compat.obj` by default because we're compiling the module files `std.ixx` and `std.compat.obj`. + - [`/ifcOutput`](../build/reference/ifc-output.md) sets the name of the named module interface file (`.ifc`). For example, `/ifcOutput "somethingelse.ifc"`. By default, the compiler uses the same name as the module source file (`.ixx`) you are compiling. In the example, the generated `ifc` files are `std.ifc` and `std.compat.ifc` by default because we're compiling the module files `std.ixx` and `std.compat.ixx`. 1. To try out importing the `std.compat` library, create a file named `stdCompatExample.cpp` with the following content: @@ -185,19 +189,19 @@ Before you can use `import std.compat;` you must compile the module interface fi cl /std:c++latest /EHsc /nologo /W4 stdCompatExample.cpp std.obj std.compat.obj ``` - We didn't have to specify `std.compat.ifc` on the command line because the compiler automatically looks for the `.ifc` file that matches the module name in an `import` statement. When the compiler encounters `import std.compat;` it finds `std.compat.ifc` since we put it in the same directory as the source code--relieving us of the need to specify it on the command line. If the `.ifc` file is in a different directory than the source code, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. + We didn't have to specify `std.compat.ifc` on the command line because the compiler automatically looks for the `.ifc` file that matches the module name in an `import` statement. When the compiler encounters `import std.compat;` it finds `std.compat.ifc` since we put it in the same directory as the source code--relieving us of the need to specify it on the command line. If the `.ifc` file is in a different directory than the source code, or has a different name, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. - Even though we're importing `std.compat`, you must also link against `std.obj` because that is where the standard library implementation lives that `std.compat` builds upon. + When you import `std.compat`, you must also link against `std.obj` because `std.compat` builds on top of the implementation in `std.obj`. If you don't link against `std.obj`, you'll get linker errors such as `LNK2019: unresolved external symbol "public: __cdecl std::vector >::~vector >(void) noexcept"` - If you're building a single project, you can combine the step of building the `std` and `std.compat` standard library named modules with the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` and `"%VCToolsInstallDir%\modules\std.compat.ixx"` (in that order) to the command line. Make sure to put them before any `.cpp` files that consume them, and specify `/Fe` to name the built `exe` as shown in this example: + If you're building a single project, you can combine the steps of building the `std` and `std.compat` standard library named modules with the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` and `"%VCToolsInstallDir%\modules\std.compat.ixx"` (in that order) to the command line. Make sure to put them before any `.cpp` files that consume them, and specify `/Fe` to name the built `exe` as shown in this example: ```cmd cl /FestdCompatExample /std:c++latest /EHsc /nologo /W4 "%VCToolsInstallDir%\modules\std.ixx" "%VCToolsInstallDir%\modules\std.compat.ixx" stdCompatExample.cpp ``` - I've shown them as separate steps in this tutorial because you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects. But it may be convenient to build them all at once. + This tutorial shows building the standard library modules as a separate step because you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects. But if it's convenient to build them all at once, you can. - The previous compiler command produces an executable named `stdCompatExample.exe`. When you run it, it produces the following output: + The previous compiler command produces an executable named `stdCompatExample.exe`. When you run it, it produces the following output: ```output Import std.compat to get global names like printf() From e531d98fabb70196357c9054974c3a9eb38b4dac Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Fri, 26 Jan 2024 15:38:14 -0800 Subject: [PATCH 09/14] more updates --- docs/cpp/tutorial-import-stl-named-module.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/cpp/tutorial-import-stl-named-module.md b/docs/cpp/tutorial-import-stl-named-module.md index 5a95f3ec772..3bf78c149be 100644 --- a/docs/cpp/tutorial-import-stl-named-module.md +++ b/docs/cpp/tutorial-import-stl-named-module.md @@ -57,7 +57,7 @@ The statement `import std;` or `import std.compat;` imports the standard library ### Example: `std` -1. Open a x86 Native Tools Command Prompt for VS: from the Windows **Start** menu, type *x86 native* and the prompt should appear in the list of apps. Ensure that the prompt is for Visual Studio 2022 preview version 17.5 or above. You'll get errors if you use the wrong version of the prompt. The examples used in this tutorial are for the CMD shell. If you use PowerShell, use `"$Env:VCToolsInstallDir\modules\std.ixx"` instead of `"%VCToolsInstallDir\modules\std.ixx"`. +1. Open a x86 Native Tools Command Prompt for VS: from the Windows **Start** menu, type *x86 native* and the prompt should appear in the list of apps. Ensure that the prompt is for Visual Studio 2022 version 17.5 or above. You'll get errors if you use the wrong version of the prompt. The examples used in this tutorial are for the CMD shell. 1. Create a directory, such as `%USERPROFILE%\source\repos\STLModules`, and make it the current directory. If you choose a directory that you don't have write access to, you'll get errors during compilation such as not being able to open the output file `std.ifc`. 1. Compile the `std` named module with the following command: @@ -67,7 +67,7 @@ The statement `import std;` or `import std.compat;` imports the standard library If you get errors, ensure that you're using the correct version of the command prompt. If you're still having issues, please file a bug at [Visual Studio Developer Community](https://developercommunity.visualstudio.com/home). - Compile the `std` named module using the same compiler settings that you intend to use with the code that imports it. If you have a multi-project solution, you can compile the standard library named module once, and then refer to it from all of your projects by using the [`/reference`](../build/reference/module-reference.md) compiler option. + Compile the `std` named module using the same compiler settings that you intend to use with the code that imports the built module. If you have a multi-project solution, you can compile the standard library named module once, and then refer to it from all of your projects by using the [`/reference`](../build/reference/module-reference.md) compiler option. Using the previous compiler command, the compiler outputs two files: - `std.ifc` is the compiled binary representation of the named module interface that the compiler consults to process the `import std;` statement. This is a compile-time only artifact. It doesn't ship with your application. @@ -86,7 +86,7 @@ The statement `import std;` or `import std.compat;` imports the standard library - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo "somethingelse.obj"`. By default, the compiler uses the same name as the module source file (`.ixx`) you are compiling. In the example, the output name is `std.obj` by default because we're compiling the module file `std.ixx`. - [`/ifcOutput`](../build/reference/ifc-output.md) sets the name of the named module interface file (`.ifc`). For example, `/ifcOutput "somethingelse.ifc"`. By default, the compiler uses the same name as the module source file (`.ixx`) you are compiling. In the example, the generated `ifc` file is `std.ifc` by default because we're compiling the module file `std.ixx`. -1. Importing the `std` library you just built by creating a file named `importExample.cpp` with the following content: +1. Importing the `std` library you just built by first creating a file named `importExample.cpp` with the following content: ```cpp // requires /std:c++latest @@ -142,7 +142,7 @@ The `std.compat` named module is a compatibility layer provided to ease migratin Before you can use `import std.compat;` you must compile the module interface file found in source code form in `std.compat.ixx`. Visual Studio ships the source code for the module so that you can compile the module using the compiler settings that match your project. The steps are similar to for building the `std` named module. The `std` named module is built first because `std.compat` depends on it: -1. Open a Native Tools Command Prompt for VS: from the Windows **Start** menu, type *x86 native* and the prompt should appear in the list of apps. Ensure that the prompt is for Visual Studio 2022 preview version 17.5 or above. You'll get compiler errors if you use the wrong version of the prompt. +1. Open a Native Tools Command Prompt for VS: from the Windows **Start** menu, type *x86 native* and the prompt should appear in the list of apps. Ensure that the prompt is for Visual Studio 2022 version 17.5 or above. You'll get compiler errors if you use the wrong version of the prompt. 1. Create a directory to try this example, such as `%USERPROFILE%\source\repos\STLModules`, and make it the current directory. If you choose a directory that you don't have write access to, you'll get errors such as not being able to open the output file `std.ifc`. 1. Compile the `std` and `std.compat` named modules with the following command: @@ -152,14 +152,14 @@ Before you can use `import std.compat;` you must compile the module interface fi You should compile `std` and `std.compat` using the same compiler settings that you intend to use with the code that imports them. If you have a multi-project solution, you can compile them once, and then refer to them from all of your projects using the [`/reference`](../build/reference/module-reference.md) compiler option. - If you get errors, ensure that you're using the correct version of the command prompt. If you're still having issues, please file a bug at [Visual Studio Developer Community](https://developercommunity.visualstudio.com/home). While this feature is still in preview, you can find a list of known problems under [Standard library header units and modules tracking issue 1694](https://github.com/microsoft/stl/issues/1694). + If you get errors, ensure that you're using the correct version of the command prompt. If you're still having issues, please file a bug at [Visual Studio Developer Community](https://developercommunity.visualstudio.com/home). The compiler outputs four files from the previous two steps: - `std.ifc` is the compiled binary named module interface that the compiler consults to process the `import std;` statement. The compiler also consults `std.ifc` to process `import std.compat;` because `std.compat` builds on `std`. This is a compile-time only artifact. It doesn't ship with your application. - `std.obj` contains the implementation of the standard library. - `std.compat.ifc` is the compiled binary named module interface that the compiler consults to process the `import std.compat;` statement. This is a compile-time only artifact. It doesn't ship with your application. - `std.compat.obj` contains implementation. However, most of the implementation is provided by `std.obj`. Add `std.obj` to the command line when you compile the sample app to statically link the functionality that you use from the standard library into your application. - - + As before in the `std` example, you can control the object file name and the named module interface file name with the following switches: - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo "somethingelse.obj"`. By default, the compiler uses the same name as the module source file (`.ixx`) you are compiling. In the example, the output names are `std.obj` and `std.compat.obj` by default because we're compiling the module files `std.ixx` and `std.compat.obj`. - [`/ifcOutput`](../build/reference/ifc-output.md) sets the name of the named module interface file (`.ifc`). For example, `/ifcOutput "somethingelse.ifc"`. By default, the compiler uses the same name as the module source file (`.ixx`) you are compiling. In the example, the generated `ifc` files are `std.ifc` and `std.compat.ifc` by default because we're compiling the module files `std.ixx` and `std.compat.ixx`. @@ -191,7 +191,7 @@ Before you can use `import std.compat;` you must compile the module interface fi We didn't have to specify `std.compat.ifc` on the command line because the compiler automatically looks for the `.ifc` file that matches the module name in an `import` statement. When the compiler encounters `import std.compat;` it finds `std.compat.ifc` since we put it in the same directory as the source code--relieving us of the need to specify it on the command line. If the `.ifc` file is in a different directory than the source code, or has a different name, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. - When you import `std.compat`, you must also link against `std.obj` because `std.compat` builds on top of the implementation in `std.obj`. If you don't link against `std.obj`, you'll get linker errors such as `LNK2019: unresolved external symbol "public: __cdecl std::vector >::~vector >(void) noexcept"` + When you import `std.compat`, you must also link against `std.obj` because `std.compat` builds on top of the implementation in `std.obj`. If you're building a single project, you can combine the steps of building the `std` and `std.compat` standard library named modules with the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` and `"%VCToolsInstallDir%\modules\std.compat.ixx"` (in that order) to the command line. Make sure to put them before any `.cpp` files that consume them, and specify `/Fe` to name the built `exe` as shown in this example: @@ -210,7 +210,7 @@ Before you can use `import std.compat;` you must compile the module interface fi ## Standard library named module considerations -Versioning for named modules is the same as for headers. The `.ixx` named module files are installed alongside the headers, for example: `"%VCToolsInstallDir%\modules\std.ixx`, which resolves to `C:\Program Files\Microsoft Visual Studio\2022\Preview\VC\Tools\MSVC\14.35.32019\modules\std.ixx` in the version of the tools used at the time of this writing. Select the version of the named module the same way you choose the version of the header file to use--by the directory you refer to them from. +Versioning for named modules is the same as for headers. The `.ixx` named module files are installed alongside the headers, for example: `"%VCToolsInstallDir%\modules\std.ixx`, which resolves to `C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.38.33130\modules\std.ixx` in the version of the tools used at the time of this writing. Select the version of the named module the same way you choose the version of the header file to use--by the directory you refer to them from. Don't mix and match importing header units and named modules. For example, don't `import ;` and `import std;` in the same file. From 6ed8e4e309597f7eb8df675cad6ec57f8363ebcb Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Fri, 26 Jan 2024 15:49:27 -0800 Subject: [PATCH 10/14] add more explanation to the 2nd scenario --- docs/cpp/tutorial-import-stl-named-module.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/cpp/tutorial-import-stl-named-module.md b/docs/cpp/tutorial-import-stl-named-module.md index 3bf78c149be..3846fead201 100644 --- a/docs/cpp/tutorial-import-stl-named-module.md +++ b/docs/cpp/tutorial-import-stl-named-module.md @@ -186,20 +186,21 @@ Before you can use `import std.compat;` you must compile the module interface fi 1. Compile the example by using the following command: ```cmd - cl /std:c++latest /EHsc /nologo /W4 stdCompatExample.cpp std.obj std.compat.obj + cl /std:c++latest /EHsc /nologo /W4 stdCompatExample.cpp + link stdCompatExample.obj std.obj std.compat.obj ``` We didn't have to specify `std.compat.ifc` on the command line because the compiler automatically looks for the `.ifc` file that matches the module name in an `import` statement. When the compiler encounters `import std.compat;` it finds `std.compat.ifc` since we put it in the same directory as the source code--relieving us of the need to specify it on the command line. If the `.ifc` file is in a different directory than the source code, or has a different name, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. When you import `std.compat`, you must also link against `std.obj` because `std.compat` builds on top of the implementation in `std.obj`. - If you're building a single project, you can combine the steps of building the `std` and `std.compat` standard library named modules with the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` and `"%VCToolsInstallDir%\modules\std.compat.ixx"` (in that order) to the command line. Make sure to put them before any `.cpp` files that consume them, and specify `/Fe` to name the built `exe` as shown in this example: + If you're building a single project, you can combine the steps of building the `std` and `std.compat` standard library named modules with the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` and `"%VCToolsInstallDir%\modules\std.compat.ixx"` (in that order) to the command line. This tutorial shows building the standard library modules as a separate step because you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects. But if it's convenient to build them all at once, you can, just make sure to put them before any `.cpp` files that consume them, and specify `/Fe` to name the built `exe` as shown in this example: ```cmd cl /FestdCompatExample /std:c++latest /EHsc /nologo /W4 "%VCToolsInstallDir%\modules\std.ixx" "%VCToolsInstallDir%\modules\std.compat.ixx" stdCompatExample.cpp ``` - This tutorial shows building the standard library modules as a separate step because you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects. But if it's convenient to build them all at once, you can. + In this example, compiling your source code and linking the module's implementation into your application are separate steps. They don't have to be. You could have used `cl /std:c++latest /EHsc /nologo /W4 stdCompatExample.cpp std.obj std.compat.obj` to compile and link in one step. But it may be convenient to build and link separately because then you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects, in your build's link step. The previous compiler command produces an executable named `stdCompatExample.exe`. When you run it, it produces the following output: From 9e1b285910eb229056523131461efb81a1a61cee Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Fri, 26 Jan 2024 16:09:35 -0800 Subject: [PATCH 11/14] edits --- docs/cpp/tutorial-import-stl-named-module.md | 39 ++++++++++---------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/docs/cpp/tutorial-import-stl-named-module.md b/docs/cpp/tutorial-import-stl-named-module.md index 3846fead201..cb7e646e7cb 100644 --- a/docs/cpp/tutorial-import-stl-named-module.md +++ b/docs/cpp/tutorial-import-stl-named-module.md @@ -55,17 +55,17 @@ The following examples demonstrate how to consume the standard library as a modu The statement `import std;` or `import std.compat;` imports the standard library into your application. But first, you must compile the standard library named modules into binary form. The following steps demonstrate how. -### Example: `std` +### Example: How to build and import `std` 1. Open a x86 Native Tools Command Prompt for VS: from the Windows **Start** menu, type *x86 native* and the prompt should appear in the list of apps. Ensure that the prompt is for Visual Studio 2022 version 17.5 or above. You'll get errors if you use the wrong version of the prompt. The examples used in this tutorial are for the CMD shell. -1. Create a directory, such as `%USERPROFILE%\source\repos\STLModules`, and make it the current directory. If you choose a directory that you don't have write access to, you'll get errors during compilation such as not being able to open the output file `std.ifc`. +1. Create a directory, such as `%USERPROFILE%\source\repos\STLModules`, and make it the current directory. If you choose a directory that you don't have write access to, you'll get errors during compilation. 1. Compile the `std` named module with the following command: ```cmd cl /std:c++latest /EHsc /nologo /W4 /c "%VCToolsInstallDir%\modules\std.ixx" ``` - If you get errors, ensure that you're using the correct version of the command prompt. If you're still having issues, please file a bug at [Visual Studio Developer Community](https://developercommunity.visualstudio.com/home). + If you get errors, ensure that you're using the correct version of the command prompt. Compile the `std` named module using the same compiler settings that you intend to use with the code that imports the built module. If you have a multi-project solution, you can compile the standard library named module once, and then refer to it from all of your projects by using the [`/reference`](../build/reference/module-reference.md) compiler option. @@ -83,8 +83,8 @@ The statement `import std;` or `import std.compat;` imports the standard library | [`/c`](../build/reference/c-compile-without-linking.md) | Compile without linking, because we're just building the binary named module interface at this point. | You can control the object file name and the named module interface file name with the following switches: - - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo "somethingelse.obj"`. By default, the compiler uses the same name as the module source file (`.ixx`) you are compiling. In the example, the output name is `std.obj` by default because we're compiling the module file `std.ixx`. - - [`/ifcOutput`](../build/reference/ifc-output.md) sets the name of the named module interface file (`.ifc`). For example, `/ifcOutput "somethingelse.ifc"`. By default, the compiler uses the same name as the module source file (`.ixx`) you are compiling. In the example, the generated `ifc` file is `std.ifc` by default because we're compiling the module file `std.ixx`. + - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo "somethingelse.obj"`. By default, the compiler uses the same name for the object file as the module source file (`.ixx`) you're compiling. In the example, the output name is `std.obj` by default because we're compiling the module file `std.ixx`. + - [`/ifcOutput`](../build/reference/ifc-output.md) sets the name of the named module interface file (`.ifc`). For example, `/ifcOutput "somethingelse.ifc"`. By default, the compiler uses the same name for the module interface file (`.ifc`) as the module source file (`.ixx`) you're compiling. In the example, the generated `ifc` file is `std.ifc` by default because we're compiling the module file `std.ixx`. 1. Importing the `std` library you just built by first creating a file named `importExample.cpp` with the following content: @@ -113,11 +113,13 @@ The statement `import std;` or `import std.compat;` imports the standard library link importExample.obj std.obj ``` - It isn't necessary to specify `/reference "std=std.ifc"` on the command line in this example because the compiler automatically looks for the `.ifc` file matching the module name specified by the `import` statement. When the compiler encounters `import std;`, it can find `std.ifc` if it is located in the same directory as the source code. If the `.ifc` file is in a different directory than the source code, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. + It isn't necessary to specify `/reference "std=std.ifc"` on the command line in this example because the compiler automatically looks for the `.ifc` file matching the module name specified by the `import` statement. When the compiler encounters `import std;` it can find `std.ifc` if it is located in the same directory as the source code. If the `.ifc` file is in a different directory than the source code, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. - In this example, compiling your source code and linking the module's implementation into your application are separate steps. They don't have to be. You could have used `cl /std:c++latest /EHsc /nologo /W4 /reference "std=std.ifc" importExample.cpp std.obj` to compile and link in one step. But it may be convenient to build and link separately because then you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects, in your build's link step. + In this example, compiling your source code and linking the module's implementation into your application are separate steps. They don't have to be. You could use `cl /std:c++latest /EHsc /nologo /W4 /reference "std=std.ifc" importExample.cpp std.obj` to compile and link in one step. But it may be convenient to build and link separately because then you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects, in your build's link step. - If you're building a single project, you can combine the steps of building the `std` standard library named module and the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` to the command line. Make sure to put it before any `.cpp` files that consume it. By default, the output executable's name is taken from the first input file. Use the `/Fe` compiler option to specify the output file name you want. This tutorial shows compiling the `std` named module as a separate step because you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects. But it may be convenient to build everything together, as shown by this command line: + If you're building a single project, you can combine the steps of building the `std` standard library named module and the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` to the command line. Put it before any `.cpp` files that consume the `std` module. + + By default, the output executable's name is taken from the first input file. Use the `/Fe` compiler option to specify the output file name you want. This tutorial shows compiling the `std` named module as a separate step because you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects. But it may be convenient to build everything together, as shown by this command line: ```cmd cl /FeimportExample /std:c++latest /EHsc /nologo /W4 "%VCToolsInstallDir%\modules\std.ixx" importExample.cpp @@ -130,20 +132,18 @@ The statement `import std;` or `import std.compat;` imports the standard library 555 ``` - The key command-line switches in this example are the same as the previous example, except that the `/c` switch isn't used. - ## Import the standard library and global C functions with `std.compat` The C++ standard library includes the ISO C standard library. The `std.compat` module provides all of the functionality of the `std` module like `std::vector`, `std::cout`, `std::printf`, `std::scanf`, and so on. But it also provides the global namespace versions of these functions such as `::printf`, `::scanf`, `::fopen`, `::size_t`, and so on. The `std.compat` named module is a compatibility layer provided to ease migrating existing code that refers to C runtime functions in the global namespace. If you want to avoid adding names to the global namespace, use `import std;`. If you need to ease migrating a codebase that uses many unqualified (global namespace) C runtime functions, use `import std.compat;`. This provides the global namespace C runtime names so that you don't have to qualify all the global names with `std::`. If you don't have any existing code that uses the global namespace C runtime functions, then you don't need to use `import std.compat;`. If you only call a few C runtime functions in your code, it may be better to use `import std;` and qualify the few global namespace C runtime names that need it with `std::`. For example, `std::printf()`. If you see an error like `error C3861: 'printf': identifier not found` when you try to compile your code, consider using `import std.compat;` to import the global namespace C runtime functions. -### Example: `std.compat` +### Example: How to build and import `std.compat` Before you can use `import std.compat;` you must compile the module interface file found in source code form in `std.compat.ixx`. Visual Studio ships the source code for the module so that you can compile the module using the compiler settings that match your project. The steps are similar to for building the `std` named module. The `std` named module is built first because `std.compat` depends on it: 1. Open a Native Tools Command Prompt for VS: from the Windows **Start** menu, type *x86 native* and the prompt should appear in the list of apps. Ensure that the prompt is for Visual Studio 2022 version 17.5 or above. You'll get compiler errors if you use the wrong version of the prompt. -1. Create a directory to try this example, such as `%USERPROFILE%\source\repos\STLModules`, and make it the current directory. If you choose a directory that you don't have write access to, you'll get errors such as not being able to open the output file `std.ifc`. +1. Create a directory to try this example, such as `%USERPROFILE%\source\repos\STLModules`, and make it the current directory. If you choose a directory that you don't have write access to, you'll get errors. 1. Compile the `std` and `std.compat` named modules with the following command: ```cmd @@ -152,7 +152,7 @@ Before you can use `import std.compat;` you must compile the module interface fi You should compile `std` and `std.compat` using the same compiler settings that you intend to use with the code that imports them. If you have a multi-project solution, you can compile them once, and then refer to them from all of your projects using the [`/reference`](../build/reference/module-reference.md) compiler option. - If you get errors, ensure that you're using the correct version of the command prompt. If you're still having issues, please file a bug at [Visual Studio Developer Community](https://developercommunity.visualstudio.com/home). + If you get errors, ensure that you're using the correct version of the command prompt. The compiler outputs four files from the previous two steps: - `std.ifc` is the compiled binary named module interface that the compiler consults to process the `import std;` statement. The compiler also consults `std.ifc` to process `import std.compat;` because `std.compat` builds on `std`. This is a compile-time only artifact. It doesn't ship with your application. @@ -160,9 +160,9 @@ Before you can use `import std.compat;` you must compile the module interface fi - `std.compat.ifc` is the compiled binary named module interface that the compiler consults to process the `import std.compat;` statement. This is a compile-time only artifact. It doesn't ship with your application. - `std.compat.obj` contains implementation. However, most of the implementation is provided by `std.obj`. Add `std.obj` to the command line when you compile the sample app to statically link the functionality that you use from the standard library into your application. - As before in the `std` example, you can control the object file name and the named module interface file name with the following switches: - - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo "somethingelse.obj"`. By default, the compiler uses the same name as the module source file (`.ixx`) you are compiling. In the example, the output names are `std.obj` and `std.compat.obj` by default because we're compiling the module files `std.ixx` and `std.compat.obj`. - - [`/ifcOutput`](../build/reference/ifc-output.md) sets the name of the named module interface file (`.ifc`). For example, `/ifcOutput "somethingelse.ifc"`. By default, the compiler uses the same name as the module source file (`.ixx`) you are compiling. In the example, the generated `ifc` files are `std.ifc` and `std.compat.ifc` by default because we're compiling the module files `std.ixx` and `std.compat.ixx`. + You can control the object file name and the named module interface file name with the following switches: + - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo "somethingelse.obj"`. By default, the compiler uses the same name for the object file as the module source file (`.ixx`) you're compiling. In the example, the output names are `std.obj` and `std.compat.obj` by default because we're compiling the module files `std.ixx` and `std.compat.obj`. + - [`/ifcOutput`](../build/reference/ifc-output.md) sets the name of the named module interface file (`.ifc`). For example, `/ifcOutput "somethingelse.ifc"`. By default, the compiler uses the same name for the module interface file (`.ifc`) as the module source file (`.ixx`) you're compiling. In the example, the generated `ifc` files are `std.ifc` and `std.compat.ifc` by default because we're compiling the module files `std.ixx` and `std.compat.ixx`. 1. To try out importing the `std.compat` library, create a file named `stdCompatExample.cpp` with the following content: @@ -192,15 +192,16 @@ Before you can use `import std.compat;` you must compile the module interface fi We didn't have to specify `std.compat.ifc` on the command line because the compiler automatically looks for the `.ifc` file that matches the module name in an `import` statement. When the compiler encounters `import std.compat;` it finds `std.compat.ifc` since we put it in the same directory as the source code--relieving us of the need to specify it on the command line. If the `.ifc` file is in a different directory than the source code, or has a different name, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. - When you import `std.compat`, you must also link against `std.obj` because `std.compat` builds on top of the implementation in `std.obj`. + When you import `std.compat`, you must also link against `std.obj` because `std.compat` builds on the implementation in `std.obj`. If you're building a single project, you can combine the steps of building the `std` and `std.compat` standard library named modules with the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` and `"%VCToolsInstallDir%\modules\std.compat.ixx"` (in that order) to the command line. This tutorial shows building the standard library modules as a separate step because you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects. But if it's convenient to build them all at once, you can, just make sure to put them before any `.cpp` files that consume them, and specify `/Fe` to name the built `exe` as shown in this example: ```cmd - cl /FestdCompatExample /std:c++latest /EHsc /nologo /W4 "%VCToolsInstallDir%\modules\std.ixx" "%VCToolsInstallDir%\modules\std.compat.ixx" stdCompatExample.cpp + cl /c /FestdCompatExample /std:c++latest /EHsc /nologo /W4 "%VCToolsInstallDir%\modules\std.ixx" "%VCToolsInstallDir%\modules\std.compat.ixx" stdCompatExample.cpp + link stdCompatExample.obj std.obj std.compat.obj ``` - In this example, compiling your source code and linking the module's implementation into your application are separate steps. They don't have to be. You could have used `cl /std:c++latest /EHsc /nologo /W4 stdCompatExample.cpp std.obj std.compat.obj` to compile and link in one step. But it may be convenient to build and link separately because then you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects, in your build's link step. + In this example, compiling your source code and linking the module's implementation into your application are separate steps. They don't have to be. You could use `cl /std:c++latest /EHsc /nologo /W4 stdCompatExample.cpp std.obj std.compat.obj` to compile and link in one step. But it may be convenient to build and link separately because then you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects, in your build's link step. The previous compiler command produces an executable named `stdCompatExample.exe`. When you run it, it produces the following output: From 834f51babe6d5936c675fbc71504e463b6b09582 Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Fri, 26 Jan 2024 16:26:14 -0800 Subject: [PATCH 12/14] some acrolinx and last edits --- docs/cpp/tutorial-import-stl-named-module.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/cpp/tutorial-import-stl-named-module.md b/docs/cpp/tutorial-import-stl-named-module.md index cb7e646e7cb..2136e7b1cc9 100644 --- a/docs/cpp/tutorial-import-stl-named-module.md +++ b/docs/cpp/tutorial-import-stl-named-module.md @@ -83,7 +83,7 @@ The statement `import std;` or `import std.compat;` imports the standard library | [`/c`](../build/reference/c-compile-without-linking.md) | Compile without linking, because we're just building the binary named module interface at this point. | You can control the object file name and the named module interface file name with the following switches: - - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo "somethingelse.obj"`. By default, the compiler uses the same name for the object file as the module source file (`.ixx`) you're compiling. In the example, the output name is `std.obj` by default because we're compiling the module file `std.ixx`. + - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo "somethingelse.obj"`. By default, the compiler uses the same name for the object file as the module source file (`.ixx`) you're compiling. In the example, the object file name is `std.obj` by default because we're compiling the module file `std.ixx`. - [`/ifcOutput`](../build/reference/ifc-output.md) sets the name of the named module interface file (`.ifc`). For example, `/ifcOutput "somethingelse.ifc"`. By default, the compiler uses the same name for the module interface file (`.ifc`) as the module source file (`.ixx`) you're compiling. In the example, the generated `ifc` file is `std.ifc` by default because we're compiling the module file `std.ixx`. 1. Importing the `std` library you just built by first creating a file named `importExample.cpp` with the following content: @@ -113,13 +113,13 @@ The statement `import std;` or `import std.compat;` imports the standard library link importExample.obj std.obj ``` - It isn't necessary to specify `/reference "std=std.ifc"` on the command line in this example because the compiler automatically looks for the `.ifc` file matching the module name specified by the `import` statement. When the compiler encounters `import std;` it can find `std.ifc` if it is located in the same directory as the source code. If the `.ifc` file is in a different directory than the source code, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. + It isn't necessary to specify `/reference "std=std.ifc"` on the command line in this example because the compiler automatically looks for the `.ifc` file matching the module name specified by the `import` statement. When the compiler encounters `import std;` it can find `std.ifc` if it's located in the same directory as the source code. If the `.ifc` file is in a different directory than the source code, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. - In this example, compiling your source code and linking the module's implementation into your application are separate steps. They don't have to be. You could use `cl /std:c++latest /EHsc /nologo /W4 /reference "std=std.ifc" importExample.cpp std.obj` to compile and link in one step. But it may be convenient to build and link separately because then you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects, in your build's link step. + In this example, compiling the source code and linking the module's implementation into your application are separate steps. They don't have to be. You could use `cl /std:c++latest /EHsc /nologo /W4 /reference "std=std.ifc" importExample.cpp std.obj` to compile and link in one step. But it may be convenient to build and link separately because then you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects, in your build's link step. If you're building a single project, you can combine the steps of building the `std` standard library named module and the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` to the command line. Put it before any `.cpp` files that consume the `std` module. - By default, the output executable's name is taken from the first input file. Use the `/Fe` compiler option to specify the output file name you want. This tutorial shows compiling the `std` named module as a separate step because you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects. But it may be convenient to build everything together, as shown by this command line: + By default, the output executable's name is taken from the first input file. Use the `/Fe` compiler option to specify the executable file name you want. This tutorial shows compiling the `std` named module as a separate step because you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects. But it may be convenient to build everything together, as shown by this command line: ```cmd cl /FeimportExample /std:c++latest /EHsc /nologo /W4 "%VCToolsInstallDir%\modules\std.ixx" importExample.cpp @@ -161,10 +161,10 @@ Before you can use `import std.compat;` you must compile the module interface fi - `std.compat.obj` contains implementation. However, most of the implementation is provided by `std.obj`. Add `std.obj` to the command line when you compile the sample app to statically link the functionality that you use from the standard library into your application. You can control the object file name and the named module interface file name with the following switches: - - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo "somethingelse.obj"`. By default, the compiler uses the same name for the object file as the module source file (`.ixx`) you're compiling. In the example, the output names are `std.obj` and `std.compat.obj` by default because we're compiling the module files `std.ixx` and `std.compat.obj`. + - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo "somethingelse.obj"`. By default, the compiler uses the same name for the object file as the module source file (`.ixx`) you're compiling. In the example, the object file names are `std.obj` and `std.compat.obj` by default because we're compiling the module files `std.ixx` and `std.compat.obj`. - [`/ifcOutput`](../build/reference/ifc-output.md) sets the name of the named module interface file (`.ifc`). For example, `/ifcOutput "somethingelse.ifc"`. By default, the compiler uses the same name for the module interface file (`.ifc`) as the module source file (`.ixx`) you're compiling. In the example, the generated `ifc` files are `std.ifc` and `std.compat.ifc` by default because we're compiling the module files `std.ixx` and `std.compat.ixx`. -1. To try out importing the `std.compat` library, create a file named `stdCompatExample.cpp` with the following content: +1. Try out importing the `std.compat` library by first creating a file named `stdCompatExample.cpp` with the following content: ```cpp import std.compat; @@ -192,16 +192,16 @@ Before you can use `import std.compat;` you must compile the module interface fi We didn't have to specify `std.compat.ifc` on the command line because the compiler automatically looks for the `.ifc` file that matches the module name in an `import` statement. When the compiler encounters `import std.compat;` it finds `std.compat.ifc` since we put it in the same directory as the source code--relieving us of the need to specify it on the command line. If the `.ifc` file is in a different directory than the source code, or has a different name, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. - When you import `std.compat`, you must also link against `std.obj` because `std.compat` builds on the implementation in `std.obj`. + When you import `std.compat`, you must link against both `std.compat` and `std.obj` because `std.compat` builds on the implementation in `std.obj`. - If you're building a single project, you can combine the steps of building the `std` and `std.compat` standard library named modules with the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` and `"%VCToolsInstallDir%\modules\std.compat.ixx"` (in that order) to the command line. This tutorial shows building the standard library modules as a separate step because you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects. But if it's convenient to build them all at once, you can, just make sure to put them before any `.cpp` files that consume them, and specify `/Fe` to name the built `exe` as shown in this example: + If you're building a single project, you can combine the steps of building the `std` and `std.compat` standard library named modules by adding `"%VCToolsInstallDir%\modules\std.ixx"` and `"%VCToolsInstallDir%\modules\std.compat.ixx"` (in that order) to the command line. This tutorial shows building the standard library modules as a separate step because you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects. But if it's convenient to build them all at once, make sure to put them before any `.cpp` files that consume them, and specify `/Fe` to name the built `exe` as shown in this example: ```cmd cl /c /FestdCompatExample /std:c++latest /EHsc /nologo /W4 "%VCToolsInstallDir%\modules\std.ixx" "%VCToolsInstallDir%\modules\std.compat.ixx" stdCompatExample.cpp link stdCompatExample.obj std.obj std.compat.obj ``` - In this example, compiling your source code and linking the module's implementation into your application are separate steps. They don't have to be. You could use `cl /std:c++latest /EHsc /nologo /W4 stdCompatExample.cpp std.obj std.compat.obj` to compile and link in one step. But it may be convenient to build and link separately because then you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects, in your build's link step. + In this example, compiling the source code and linking the module's implementation into your application are separate steps. They don't have to be. You could use `cl /std:c++latest /EHsc /nologo /W4 stdCompatExample.cpp std.obj std.compat.obj` to compile and link in one step. But it may be convenient to build and link separately because then you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects, in your build's link step. The previous compiler command produces an executable named `stdCompatExample.exe`. When you run it, it produces the following output: From caf476cbf273cf8abf155b8b15944aa8bdca2bda Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Fri, 26 Jan 2024 16:34:33 -0800 Subject: [PATCH 13/14] fix #4158 --- docs/atl-mfc-shared/reference/csimplestringt-class.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/atl-mfc-shared/reference/csimplestringt-class.md b/docs/atl-mfc-shared/reference/csimplestringt-class.md index cfc4bffc408..f739673cb63 100644 --- a/docs/atl-mfc-shared/reference/csimplestringt-class.md +++ b/docs/atl-mfc-shared/reference/csimplestringt-class.md @@ -515,11 +515,7 @@ LPTSTR pstr = str.GetBufferSetLength(3); pstr[0] = _T('C'); pstr[1] = _T('u'); pstr[2] = _T('p'); - -// No need for trailing zero or call to ReleaseBuffer() -// because GetBufferSetLength() set it for us. -// If we had called GetBuffer() instead of GetBufferSetLength() -// then we would have needed to call ReleaseBuffer(). +str.ReleaseBuffer(); str += _T(" soccer is best!"); ASSERT(_tcscmp(str, _T("Cup soccer is best!")) == 0); From 5dbe71d7225ff5a30b681f5b3a603e4ad6dbcf2b Mon Sep 17 00:00:00 2001 From: TylerMSFT Date: Fri, 26 Jan 2024 16:58:29 -0800 Subject: [PATCH 14/14] fix github #2749 as well --- .../atl-mfc-shared/reference/csimplestringt-class.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/atl-mfc-shared/reference/csimplestringt-class.md b/docs/atl-mfc-shared/reference/csimplestringt-class.md index f739673cb63..f45b0dee601 100644 --- a/docs/atl-mfc-shared/reference/csimplestringt-class.md +++ b/docs/atl-mfc-shared/reference/csimplestringt-class.md @@ -1162,19 +1162,19 @@ The following example demonstrates the use of `CSimpleStringT::Truncate`. CAtlString basestr; IAtlStringMgr* pMgr = basestr.GetManager(); CSimpleString str(_T("abcdefghi"), pMgr); -_tprintf_s(_T("Allocated length: %d\n"), str.GetLength()); -_tprintf_s(_T("Contents: %s\n"), str); +_tprintf_s(_T("String length: %d / Allocated length: %d\n"), str.GetLength(), str.GetAllocLength()); +_tprintf_s(_T("Contents: %s\n"), (LPCTSTR)str); str.Truncate(4); -_tprintf_s(_T("Allocated length: %d\n"), str.GetLength()); -_tprintf_s(_T("Contents: %s\n"), str); +_tprintf_s(_T("String length: %d / Allocated length: %d\n"), str.GetLength(), , str.GetAllocLength()); +_tprintf_s(_T("Contents: %s\n"), (LPCTSTR)str); ``` The output from this example is: ```Output -Allocated length: 9 +String length: 9 / Allocated length: 15 Contents: abcdefghi -Allocated length: 4 +String length: 4 / Allocated length: 15 Contents: abcd ```