diff --git a/docs/build/reference/common-macros-for-build-commands-and-properties.md b/docs/build/reference/common-macros-for-build-commands-and-properties.md index 6cee9dc83c6..e8e5c7d8eb3 100644 --- a/docs/build/reference/common-macros-for-build-commands-and-properties.md +++ b/docs/build/reference/common-macros-for-build-commands-and-properties.md @@ -37,7 +37,7 @@ This table describes a commonly used subset of the available macros; there are m |**$(ProjectName)**|The base name of the project.| |**$(ProjectPath)**|The absolute path name of the project (defined as drive + path + base name + file extension).| |**$(PublishDir)**|The output location for the publish target; includes the trailing backslash '\\'. Defaults to the **$(OutDir)app.publish\\** folder.| -|**$(RemoteMachine)**|Set to the value of the **Remote Machine** property on the Debug property page. See [Changing Project Settings for a C/C++ Debug Configuration](/visualstudio/debugger/project-settings-for-a-cpp-debug-configuration) for more information.| +|**$(RemoteMachine)**|Set to the value of the **Remote Machine** property on the Debug property page. For more information, see [Changing Project Settings for a C/C++ Debug Configuration](/visualstudio/debugger/project-settings-for-a-cpp-debug-configuration).| |**$(RootNameSpace)**|The namespace, if any, containing the application.| |**$(SolutionDir)**|The directory of the solution (defined as drive + path); includes the trailing backslash '\\'. Defined only when building a solution in the IDE.| |**$(SolutionExt)**|The file extension of the solution. It includes the '.' before the file extension. Defined only when building a solution in the IDE.| diff --git a/docs/build/reference/compiler-command-line-syntax.md b/docs/build/reference/compiler-command-line-syntax.md index 8cea8f4ff54..6936391ed25 100644 --- a/docs/build/reference/compiler-command-line-syntax.md +++ b/docs/build/reference/compiler-command-line-syntax.md @@ -17,10 +17,10 @@ The following table describes input to the CL command. |Entry|Meaning| |-----------|-------------| -|*option*|One or more [CL options](compiler-options.md). Note that all options apply to all specified source files. Options are specified by either a forward slash (/) or a dash (-). If an option takes an argument, the option's description documents whether a space is allowed between the option and the arguments. Option names (except for the /HELP option) are case sensitive. See [Order of CL Options](order-of-cl-options.md) for more information.| -|`file`|The name of one or more source files, .obj files, or libraries. CL compiles source files and passes the names of the .obj files and libraries to the linker. See [CL Filename Syntax](cl-filename-syntax.md) for more information.| +|*option*|One or more [CL options](compiler-options.md). Note that all options apply to all specified source files. Options are specified by either a forward slash (/) or a dash (-). If an option takes an argument, the option's description documents whether a space is allowed between the option and the arguments. Option names (except for the /HELP option) are case sensitive. For more information, see [Order of CL Options](order-of-cl-options.md).| +|`file`|The name of one or more source files, .obj files, or libraries. CL compiles source files and passes the names of the .obj files and libraries to the linker. For more information, see [CL Filename Syntax](cl-filename-syntax.md).| |*lib*|One or more library names. CL passes these names to the linker.| -|*command-file*|A file that contains multiple options and filenames. See [CL Command Files](cl-command-files.md) for more information.| +|*command-file*|A file that contains multiple options and filenames. For more information, see [CL Command Files](cl-command-files.md).| |*link-opt*|One or more [MSVC Linker Options](linker-options.md). CL passes these options to the linker.| You can specify any number of options, filenames, and library names, as long as the number of characters on the command line does not exceed 1024, the limit dictated by the operating system. diff --git a/docs/build/reference/compiling-a-c-cpp-program.md b/docs/build/reference/compiling-a-c-cpp-program.md index 5bb1e6e9380..04b7733c869 100644 --- a/docs/build/reference/compiling-a-c-cpp-program.md +++ b/docs/build/reference/compiling-a-c-cpp-program.md @@ -11,7 +11,7 @@ C and C++ compiler options can be set either in the Visual Studio IDE or on the ## In Visual Studio -You can set compiler options for each project in its Visual Studio **Property Pages** dialog box. In the left pane, select **Configuration Properties**, **C/C++** and then choose the compiler option category. The topic for each compiler option describes how it can be set and where it is found in the development environment. See [MSVC Compiler Options](compiler-options.md) for a complete list. +You can set compiler options for each project in its Visual Studio **Property Pages** dialog box. In the left pane, select **Configuration Properties**, **C/C++** and then choose the compiler option category. The topic for each compiler option describes how it can be set and where it is found in the development environment. For more information and a complete list of options, see [MSVC compiler options](compiler-options.md). ## From the command line diff --git a/docs/build/reference/creating-a-makefile-project.md b/docs/build/reference/creating-a-makefile-project.md index 3b351c0c022..2d60b22066c 100644 --- a/docs/build/reference/creating-a-makefile-project.md +++ b/docs/build/reference/creating-a-makefile-project.md @@ -50,7 +50,7 @@ The output file that you specify in the project has no effect on the name that t ::: moniker-end -You can view and edit the project's properties in its property page. See [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md) for information about displaying the property page. +You can view and edit the project's properties in its property page. For more information about displaying the property page, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). ## Makefile project wizard diff --git a/docs/build/reference/general-property-page-file.md b/docs/build/reference/general-property-page-file.md index 5b9b42230ac..f4dc2206c6b 100644 --- a/docs/build/reference/general-property-page-file.md +++ b/docs/build/reference/general-property-page-file.md @@ -21,7 +21,7 @@ When you right-click on a file node **Solution Explorer**, the **General** prope - **Item Type** - The **Item Type** specifies the tool that will be used to process the file during the build process. [Files whose extension is known to Visual Studio](/visualstudio/extensibility/visual-cpp-project-extensibility#project-items) have a default value in this property. You can specify a custom tool here if you have a custom file type or wish to override the default tool for a known file type. See [Specifying Custom Build Tools](../specifying-custom-build-tools.md) for more information. You can also use this property page to specify that a file is not part of the build process. + The **Item Type** specifies the tool that will be used to process the file during the build process. [Files whose extension is known to Visual Studio](/visualstudio/extensibility/visual-cpp-project-extensibility#project-items) have a default value in this property. You can specify a custom tool here if you have a custom file type or wish to override the default tool for a known file type. For more information, see [Specifying Custom Build Tools](../specifying-custom-build-tools.md). You can also use this property page to specify that a file is not part of the build process. The following illustration shows the property page for a *.cpp* file. The default **Item Type** for this kind of file is the **C/C++ Compiler** (*cl.exe*) and the property page exposes various compiler settings that can be applied to this file only. diff --git a/docs/build/reference/keycontainer-specify-a-key-container-to-sign-an-assembly.md b/docs/build/reference/keycontainer-specify-a-key-container-to-sign-an-assembly.md index cb7054b09ac..8ee29e44c0c 100644 --- a/docs/build/reference/keycontainer-specify-a-key-container-to-sign-an-assembly.md +++ b/docs/build/reference/keycontainer-specify-a-key-container-to-sign-an-assembly.md @@ -23,7 +23,7 @@ The linker creates a signed assembly by inserting a public key into the assembly If you compile with [/LN](ln-create-msil-module.md), the name of the key file is held in the module and incorporated into the assembly that is created when you compile an assembly that includes an explicit reference to the module, via [#using](../../preprocessor/hash-using-directive-cpp.md), or when linking with [/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md). -You can also pass your encryption information to the compiler with [/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md). Use [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) if you want a partially signed assembly. See [Strong Name Assemblies (Assembly Signing) (C++/CLI)](../../dotnet/strong-name-assemblies-assembly-signing-cpp-cli.md) for more information on signing an assembly. +You can also pass your encryption information to the compiler with [/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md). Use [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) if you want a partially signed assembly. For more information on signing an assembly, see [Strong Name Assemblies (Assembly Signing) (C++/CLI)](../../dotnet/strong-name-assemblies-assembly-signing-cpp-cli.md). Other linker options that affect assembly generation are: diff --git a/docs/build/reference/ltcg-link-time-code-generation.md b/docs/build/reference/ltcg-link-time-code-generation.md index 819e3a305a6..793acf2cc03 100644 --- a/docs/build/reference/ltcg-link-time-code-generation.md +++ b/docs/build/reference/ltcg-link-time-code-generation.md @@ -124,7 +124,7 @@ Modules that are compiled by using [`/GL`](gl-whole-program-optimization.md) and ### To set this compiler option in the Visual Studio development environment -1. Open the project **Property Pages** dialog box. See [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the project **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **General** property page. diff --git a/docs/build/reference/managing-a-library.md b/docs/build/reference/managing-a-library.md index fb27ae87eca..5ea56fcb14e 100644 --- a/docs/build/reference/managing-a-library.md +++ b/docs/build/reference/managing-a-library.md @@ -1,49 +1,47 @@ --- description: "Learn more about: Managing a Library" title: "Managing a Library" -ms.date: "11/04/2016" +ms.date: 03/02/2022 f1_keywords: ["VC.Project.VCLibrarianTool.OVERWRITEAllDefaultLibraries", "VC.Project.VCLibrarianTool.AdditionalDependencies", "VC.Project.VCLibrarianTool.RemoveObjects", "VC.Project.VCLibrarianTool.LibraryPaths", "VC.Project.VCLibrarianTool.OutputFile", "VC.Project.VCLibrarianTool.OVERWRITEDefaultLibraryNames", "VC.Project.VCLibrarianTool.AdditionalLibraryDirectories", "VC.Project.VCLibrarianTool.ListContentsFile", "VC.Project.VCLibrarianTool.ListContents", "VC.Project.VCLibrarianTool.SubSystemVersion", "VC.Project.VCLibrarianTool.OVERWRITEDefaultLibraryName", "VC.Project.VCLibrarianTool.SubSystem"] helpviewer_keywords: ["/LIBPATH library manager option", "OUT library manager option", "CONVERT library manager option", "LIBPATH library manager option", "/LIST library manager option", "object files, building and modifying", "-LINK50COMPAT library manager option", "REMOVE library manager option", "SUBSYSTEM library manager option", "/LINK50COMPAT library manager option", "/OUT library manager option", "LIB [C++], managing COFF libraries", "-CONVERT library manager option", "LINK50COMPAT library manager option", "-OUT library manager option", "-REMOVE library manager option", "-LIST library manager option", "/SUBSYSTEM library manager option", "-SUBSYSTEM library manager option", "/REMOVE library manager option", "-LIBPATH library manager option", "object files", "LIST library manager option", "/CONVERT library manager option"] ms.assetid: f56a8b85-fbdc-4c09-8d8e-00f0ffe1da53 --- # Managing a Library -The default mode for LIB is to build or modify a library of COFF objects. LIB runs in this mode when you do not specify /EXTRACT (to copy an object to a file) or /DEF (to build an import library). +The default mode for LIB is to build or modify a library of COFF objects. LIB runs in this mode when you don't specify **`/EXTRACT`** (to copy an object to a file) or **`/DEF`** (to build an import library). To build a library from objects and/or libraries, use the following syntax: -``` -LIB [options...] files... -``` +> **`LIB`** [*`options...`*] *`files...`* -This command creates a library from one or more input *files*. The *files* can be COFF object files, 32-bit OMF object files, or existing COFF libraries. LIB creates one library that contains all objects in the specified files. If an input file is a 32-bit OMF object file, LIB converts it to COFF before building the library. LIB cannot accept a 32-bit OMF object that is in a library created by the 16-bit version of LIB. You must first use the 16-bit LIB to extract the object; then you can use the extracted object file as input to the 32-bit LIB. +This command creates a library from one or more input files, *`files`*. The *`files`* can be COFF object files, 32-bit OMF object files, or existing COFF libraries. LIB creates one library that contains all objects in the specified files. If an input file is a 32-bit OMF object file, LIB converts it to COFF before building the library. LIB can't accept a 32-bit OMF object that's in a library created by the 16-bit version of LIB. You must first use the 16-bit LIB to extract the object; then you can use the extracted object file as input to the 32-bit LIB. -By default, LIB names the output file using the base name of the first object or library file and the extension .lib. The output file is put in the current directory. If a file already exists with the same name, the output file replaces the existing file. To preserve an existing library, use the /OUT option to specify a name for the output file. +By default, LIB names the output file using the base name of the first object or library file and the extension *`.lib`*. The output file is put in the current directory. If a file already exists with the same name, the output file replaces the existing file. To preserve an existing library, use the **`/OUT`** option to specify a name for the output file. The following options apply to building and modifying a library: -**/LIBPATH:** *dir*
-Overrides the environment library path. For details, see the description of the LINK [/LIBPATH](libpath-additional-libpath.md) option. +**`/LIBPATH:`** *`dir`*\ +Overrides the environment library path and sets it to *`dir`*. For details, see the description of the LINK [`/LIBPATH`](libpath-additional-libpath.md) option. -**/LIST**
-Displays information about the output library to standard output. The output can be redirected to a file. You can use /LIST to determine the contents of an existing library without modifying it. +**`/LIST`**\ +Displays information about the output library to standard output. The output can be redirected to a file. You can use **`/LIST`** to determine the contents of an existing library without modifying it. -**/NAME:** *filename*
-When building an import library, specifies the name of the DLL for which the import library is being built. +**`/NAME:`** *`filename`*\ +When building an import library, *`filename`* specifies the name of the DLL for which the import library is being built. -**/NODEFAULTLIB**
-Removes one or more default libraries from the list of libraries it searches when resolving external references. See [/NODEFAULTLIB](nodefaultlib-ignore-libraries.md) for more information. +**`/NODEFAULTLIB`**\ +Removes one or more default libraries from the list of libraries it searches when resolving external references. For more information, see [`/NODEFAULTLIB`](nodefaultlib-ignore-libraries.md). -**/OUT:** *filename*
-Overrides the default output filename. By default, the output library is created in the current directory, with the base name of the first library or object file on the command line and the extension .lib. +**`/OUT:`** *`filename`*\ +Overrides the default output filename and replaces it with *`filename`*. By default, the output library is created in the current directory, with the base name of the first library or object file on the command line and the extension *`.lib`*. -**/REMOVE:** *object*
-Omits the specified *object* from the output library. LIB creates an output library by combining all objects (whether in object files or libraries), and then deleting any objects specified with /REMOVE. +**`/REMOVE:`** *`object`*\ +Omits the specified *`object`* from the output library. LIB creates an output library by combining all objects (whether in object files or libraries), and then deleting any objects specified with **`/REMOVE`**. -**/SUBSYSTEM:**{**CONSOLE** \| **EFI_APPLICATION** \| **EFI_BOOT_SERVICE_DRIVER** \| **EFI_ROM** \| **EFI_RUNTIME_DRIVER** \| **NATIVE** \| **POSIX** \| **WINDOWS** \| **WINDOWSCE**}[,#[.##]]
-Tells the operating system how to run a program created by linking to the output library. For more information, see the description of the LINK [/SUBSYSTEM](subsystem-specify-subsystem.md) option. +**`/SUBSYSTEM:`**{**`CONSOLE`** \| **`EFI_APPLICATION`** \| **`EFI_BOOT_SERVICE_DRIVER`** \| **`EFI_ROM`** \| **`EFI_RUNTIME_DRIVER`** \| **`NATIVE`** \| **`POSIX`** \| **`WINDOWS`** \| **`WINDOWSCE`**}[,#[.##]]\ +Tells the operating system how to run a program created by linking to the output library. For more information, see the description of the LINK [`/SUBSYSTEM`](subsystem-specify-subsystem.md) option. -LIB options specified on the command line are not case sensitive. +LIB options specified on the command line aren't case sensitive. You can use LIB to perform the following library-management tasks: @@ -56,7 +54,7 @@ You can use LIB to perform the following library-management tasks: - To delete a member from a library, use the /REMOVE option. LIB processes any specifications of /REMOVE after combining all input objects, regardless of command-line order. > [!NOTE] -> You cannot both delete a member and extract it to a file in the same step. You must first extract the member object using /EXTRACT, then run LIB again using /REMOVE. This behavior differs from that of the 16-bit LIB (for OMF libraries) provided in other Microsoft products. +> You can't both delete a member and extract it to a file in the same step. You must first extract the member object using **`/EXTRACT`**, then run LIB again using **`/REMOVE`**. This behavior differs from that of the 16-bit LIB (for OMF libraries) provided in other Microsoft products. ## See also diff --git a/docs/build/reference/qfast-transcendentals-force-fast-transcendentals.md b/docs/build/reference/qfast-transcendentals-force-fast-transcendentals.md index 7259b4b09e0..4cff2b6e291 100644 --- a/docs/build/reference/qfast-transcendentals-force-fast-transcendentals.md +++ b/docs/build/reference/qfast-transcendentals-force-fast-transcendentals.md @@ -1,26 +1,24 @@ --- -description: "Learn more about: /Qfast_transcendentals (Force Fast Transcendentals)" -title: "/Qfast_transcendentals (Force Fast Transcendentals)" -ms.date: "11/04/2016" +description: "Learn more about: /Qfast_transcendentals (Force fast transcendentals)" +title: "/Qfast_transcendentals (Force fast transcendentals)" +ms.date: 03/02/2022 f1_keywords: ["/Qfast_transcendentals"] helpviewer_keywords: ["/Qfast_transcendentals", "Force Fast Transcendentals"] ms.assetid: 4de24bd1-38e6-49d4-9a05-04c9937d24ac --- -# /Qfast_transcendentals (Force Fast Transcendentals) +# `/Qfast_transcendentals` (Force fast transcendentals) Generates inline code for transcendental functions. ## Syntax -``` -/Qfast_transcendentals -``` +> **`/Qfast_transcendentals`** ## Remarks -This compiler option forces transcendental functions to be converted to inline code to improve execution speed. This option has an effect only when paired with **/fp:except** or **/fp:precise**. Generating inline code for transcendental functions is already the default behavior under **/fp:fast**. +This compiler option forces transcendental functions to be converted to inline code to improve execution speed. This option has an effect only when paired with **`/fp:except`** or **`/fp:precise`**. Generating inline code for transcendental functions is already the default behavior under **`/fp:fast`**. -This option is incompatible with **/fp:strict**. See [/fp (Specify Floating-Point Behavior)](fp-specify-floating-point-behavior.md) for more information about floating point compiler options. +This option is incompatible with **`/fp:strict`**. For more information about floating point compiler options, see [`/fp` (Specify Floating-Point Behavior)](fp-specify-floating-point-behavior.md). ### To set this compiler option in the Visual Studio development environment @@ -36,6 +34,6 @@ This option is incompatible with **/fp:strict**. See [/fp (Specify Floating-Poin ## See also -[/Q Options (Low-Level Operations)](q-options-low-level-operations.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[`/Q` Options (Low-level operations)](q-options-low-level-operations.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/safeseh-image-has-safe-exception-handlers.md b/docs/build/reference/safeseh-image-has-safe-exception-handlers.md index 23f40109f4f..76d3f2d7ee7 100644 --- a/docs/build/reference/safeseh-image-has-safe-exception-handlers.md +++ b/docs/build/reference/safeseh-image-has-safe-exception-handlers.md @@ -1,34 +1,32 @@ --- description: "Learn more about: /SAFESEH (Image has Safe Exception Handlers)" title: "/SAFESEH (Image has Safe Exception Handlers)" -ms.date: "11/04/2016" +ms.date: 03/02/2022 f1_keywords: ["/SAFESEH"] helpviewer_keywords: ["/SAFESEH linker option", "-SAFESEH linker option", "SAFESEH linker option"] ms.assetid: 7722ff99-b833-4c65-a855-aaca902ffcb7 --- -# /SAFESEH (Image has Safe Exception Handlers) +# `/SAFESEH` (Image has Safe Exception Handlers) -``` -/SAFESEH[:NO] -``` +> **`/SAFESEH`**[**`:NO`**] -When **/SAFESEH** is specified, the linker will only produce an image if it can also produce a table of the image's safe exception handlers. This table specifies for the operating system which exception handlers are valid for the image. +When **`/SAFESEH`** is specified, the linker will only produce an image if it can also produce a table of the image's safe exception handlers. This table specifies for the operating system which exception handlers are valid for the image. -**/SAFESEH** is only valid when linking for x86 targets. **/SAFESEH** is not supported for platforms that already have the exception handlers noted. For example, on x64 and ARM, all exception handlers are noted in the PDATA. ML64.exe has support for adding annotations that emit SEH information (XDATA and PDATA) into the image, allowing you to unwind through ml64 functions. See [MASM for x64 (ml64.exe)](../../assembler/masm/masm-for-x64-ml64-exe.md) for more information. +**`/SAFESEH`** is only valid when linking for x86 targets. **`/SAFESEH`** isn't supported for platforms that already have the exception handlers noted. For example, on x64 and ARM, all exception handlers are noted in the PDATA. ML64.exe has support for adding annotations that emit SEH information (XDATA and PDATA) into the image, allowing you to unwind through ml64 functions. For more information, see [MASM for x64 (ml64.exe)](../../assembler/masm/masm-for-x64-ml64-exe.md). -If **/SAFESEH** is not specified, the linker will produce an image with a table of safe exceptions handlers if all modules are compatible with the safe exception handling feature. If any modules were not compatible with safe exception handling feature, the resulting image will not contain a table of safe exception handlers. If [/SUBSYSTEM](subsystem-specify-subsystem.md) specifies WINDOWSCE or one of the EFI_* options, the linker will not attempt to produce an image with a table of safe exceptions handlers, as neither of those subsystems can make use of the information. +If **`/SAFESEH`** isn't specified, the linker will produce an image with a table of safe exceptions handlers if all code segments are compatible with the safe exception handling feature. If any code segments weren't compatible with the safe exception handling feature, the resulting image won't contain a table of safe exception handlers. If [`/SUBSYSTEM`](subsystem-specify-subsystem.md) specifies WINDOWSCE or one of the `EFI_*` options, the linker won't attempt to produce an image with a table of safe exceptions handlers, as neither of those subsystems can make use of the information. -If **/SAFESEH:NO** is specified, the linker will not produce an image with a table of safe exceptions handlers even if all modules are compatible with the safe exception handling feature. +If **`/SAFESEH:NO`** is specified, the linker won't produce an image with a table of safe exceptions handlers even if all code segments are compatible with the safe exception handling feature. -The most common reason for the linker not to be able to produce an image is because one or more of the input files (modules) to the linker was not compatible with the safe exception handlers feature. A common reason for a module to not be compatible with safe exception handlers is because it was created with a compiler from a previous version of Visual C++. +The most common reason the linker can't produce an image is because one or more of the input files to the linker was incompatible with the safe exception handlers feature. A common reason why code is incompatible with safe exception handlers is because it was created with a compiler from a previous version of Visual C++. -You can also register a function as a structured exception handler by using [.SAFESEH](../../assembler/masm/dot-safeseh.md). +You can also register a function as a structured exception handler by using [`.SAFESEH`](../../assembler/masm/dot-safeseh.md). -It is not possible to mark an existing binary as having safe exception handlers (or no exception handlers); information on safe exception handling must be added at build time. +It isn't possible to mark an existing binary as having safe exception handlers (or no exception handlers); information on safe exception handling must be added at build time. -The linker's ability to build a table of safe exception handlers depends on the application using the C runtime library. If you link with [/NODEFAULTLIB](nodefaultlib-ignore-libraries.md) and you want a table of safe exception handlers, you need to supply a load config struct (such as can be found in loadcfg.c CRT source file) that contains all the entries defined for Visual C++. For example: +The linker's ability to build a table of safe exception handlers depends on the application using the C runtime library. If you link with [`/NODEFAULTLIB`](nodefaultlib-ignore-libraries.md) and you want a table of safe exception handlers, you need to supply a load config struct (such as can be found in the *`loadcfg.c`* CRT source file) that contains all the entries defined for Visual C++. For example: -``` +```C #include extern DWORD_PTR __security_cookie; /* /GS security cookie */ @@ -103,5 +101,5 @@ const IMAGE_LOAD_CONFIG_DIRECTORY32_2 _load_config_used = { ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/section-specify-section-attributes.md b/docs/build/reference/section-specify-section-attributes.md index 50cd06a531e..e658b0c901f 100644 --- a/docs/build/reference/section-specify-section-attributes.md +++ b/docs/build/reference/section-specify-section-attributes.md @@ -1,71 +1,71 @@ --- description: "Learn more about: /SECTION (Specify Section Attributes)" title: "/SECTION (Specify Section Attributes)" -ms.date: "12/29/2017" +ms.date: 03/02/2022 f1_keywords: ["/section"] helpviewer_keywords: ["SECTION linker option", "-SECTION linker option", "section attributes", "/SECTION linker option"] --- -# /SECTION (Specify Section Attributes) +# `/SECTION` (Specify Section Attributes) -> **/SECTION:**_name_,[[**!**]{**DEKPRSW**}][**,ALIGN=**_number_] +> **`/SECTION:`***`name`***`,`**[[**`!`**]{**`D`**\|**`E`**\|**`K`**\|**`P`**\|**`R`**\|**`S`**\|**`W`**}][**`,ALIGN=`***`number`*] ## Remarks -The **/SECTION** option changes the attributes of a section, overriding the attributes set when the .obj file for the section was compiled. +The **`/SECTION`** option changes the attributes of a section, overriding the attributes set when the *`.obj`* file for the section was compiled. -A *section* in a portable executable (PE) file is a named contiguous block of memory that contains either code or data. Some sections contain code or data that your program declared and uses directly, while other data sections are created for you by the linker and library manager (lib.exe) and contain information vital to the operating system. For more information, see [PE Format](/windows/win32/Debug/pe-format). +A *section* in a portable executable (PE) file is a named contiguous block of memory that contains either code or data. Some sections contain code or data that your program declared and uses directly. Other data sections are created for you by the linker and library manager (*`lib.exe`*) and contain information vital to the operating system. For more information, see [PE Format](/windows/win32/Debug/pe-format). -Specify a colon (:) and a section *name*. The *name* is case sensitive. +Specify a colon (**`:`**) and a section name *`name`*. The *`name`* is case sensitive. -Do not use the following names, as they conflict with standard names. For example, .sdata is used on RISC platforms: +Don't use the following names, as they conflict with standard names. For example, `.sdata` is used on RISC platforms: -- .arch +- `.arch` -- .bss +- `.bss` -- .data +- `.data` -- .edata +- `.edata` -- .idata +- `.idata` -- .pdata +- `.pdata` -- .rdata +- `.rdata` -- .reloc +- `.reloc` -- .rsrc +- `.rsrc` -- .sbss +- `.sbss` -- .sdata +- `.sdata` -- .srdata +- `.srdata` -- .text +- `.text` -- .xdata +- `.xdata` -Specify one or more attributes for the section. The attribute characters, listed below, are not case sensitive. You must specify all attributes that you want the section to have; an omitted attribute character causes that attribute bit to be turned off. If you do not specify R, W, or E, the existing read, write, or executable status remains unchanged. +Specify one or more attributes for the section. The attribute characters, listed below, aren't case sensitive. You must specify all attributes that you want the section to have. An omitted attribute character causes that attribute bit to be turned off. If you don't specify `R`, `W`, or `E`, the existing read, write, or executable status remains unchanged. -To negate an attribute, precede its character with an exclamation point (!). The meanings of the attribute characters are shown in this table: +To negate an attribute, precede its character with an exclamation point (`!`). The meanings of the attribute characters are shown in this table: -|Character|Attribute|Meaning| -|---------------|---------------|-------------| -|E|Execute|The section is executable| -|R|Read|Allows read operations on data| -|W|Write|Allows write operations on data| -|S|Shared|Shares the section among all processes that load the image| -|D|Discardable|Marks the section as discardable| -|K|Cacheable|Marks the section as not cacheable| -|P|Pageable|Marks the section as not pageable| +| Character | Attribute | Meaning | +|--|--|--| +| `E` | Execute | The section is executable | +| `R` | Read | Allows read operations on data | +| `W` | Write | Allows write operations on data | +| `S` | Shared | Shares the section among all processes that load the image | +| `D` | Discardable | Marks the section as discardable | +| `K` | Cacheable | Marks the section as not cacheable | +| `P` | Pageable | Marks the section as not pageable | -K and P are unusual in that the section flags that correspond to them are used in the negative sense. If you specify one of them on the .text section by using the **/SECTION:.text,K** option, there is no difference in the section flags when you run [DUMPBIN](dumpbin-options.md) with the [/HEADERS](headers.md) option; the section was already implicitly cached. To remove the default, specify **/SECTION:.text,!K** instead. DUMPBIN reveals section characteristics, including "Not Cached." +`K` and `P` are unusual in that the section flags that correspond to them are used in the negative sense. If you specify one of them on the `.text` section by using the **`/SECTION:.text,K`** option, there's no difference in the section flags when you run [`DUMPBIN`](dumpbin-options.md) with the [`/HEADERS`](headers.md) option; the section was already implicitly cached. To remove the default, specify **`/SECTION:.text,!K`** instead. DUMPBIN reveals section characteristics, including "Not Cached." -A section in the PE file that does not have E, R, or W set is probably invalid. +A section in the PE file that doesn't have `E`, `R`, or `W` set is probably invalid. -The **ALIGN=**_number_ argument lets you specify an alignment value for a particular section. The _number_ argument is in bytes and must be a power of two. See [/ALIGN](align-section-alignment.md) for more information. +The **`ALIGN=`***`number`* argument lets you specify an alignment value for a particular section. The *`number`* argument is in bytes and must be a power of two. For more information, see [`/ALIGN`](align-section-alignment.md). ### To set this linker option in the Visual Studio development environment @@ -81,5 +81,5 @@ The **ALIGN=**_number_ argument lets you specify an alignment value for a partic ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/tsaware-create-terminal-server-aware-application.md b/docs/build/reference/tsaware-create-terminal-server-aware-application.md index e5d398e9d6a..3b060a4c75c 100644 --- a/docs/build/reference/tsaware-create-terminal-server-aware-application.md +++ b/docs/build/reference/tsaware-create-terminal-server-aware-application.md @@ -1,32 +1,30 @@ --- -description: "Learn more about: /TSAWARE (Create Terminal Server Aware Application)" -title: "/TSAWARE (Create Terminal Server Aware Application)" -ms.date: "11/04/2016" +description: "Learn more about: /TSAWARE (Create Terminal Server aware application)" +title: "/TSAWARE (Create Terminal Server aware application)" +ms.date: 03/02/2022 f1_keywords: ["/tsaware", "VC.Project.VCLinkerTool.TerminalServerAware"] helpviewer_keywords: ["Terminal Server", "/TSAWARE linker option", "Terminal Server, Terminal Server-aware applications", "-TSAWARE linker option", "TSAWARE linker option"] ms.assetid: fe1c1846-de5b-4839-b562-93fbfe36cd29 --- -# /TSAWARE (Create Terminal Server Aware Application) +# `/TSAWARE` (Create Terminal Server aware application) -``` -/TSAWARE[:NO] -``` +> **`/TSAWARE`**\[**`:NO`**] ## Remarks -The /TSAWARE option sets a flag in the IMAGE_OPTIONAL_HEADER DllCharacteristics field in the program image's optional header. When this flag is set, Terminal Server will not make certain changes to the application. +The **`/TSAWARE`** option sets a flag in the `IMAGE_OPTIONAL_HEADER` `DllCharacteristics` field in the program image's optional header. When this flag is set, Terminal Server won't make certain changes to the application. -When an application is not Terminal Server aware (also known as a legacy application), Terminal Server makes certain modifications to the legacy application to make it work properly in a multiuser environment. For example, Terminal Server will create a virtual Windows folder, such that each user gets a Windows folder instead of getting the system's Windows directory. This gives users access to their own INI files. In addition, Terminal Server makes some adjustments to the registry for a legacy application. These modifications slow the loading of the legacy application on Terminal Server. +When an application isn't Terminal Server aware (also known as a legacy application), Terminal Server makes certain modifications to the legacy application to make it work properly in a multiuser environment. For example, Terminal Server creates a virtual *`Windows`* folder, such that each user gets a *`Windows`* folder instead of getting the system's *`Windows`* directory. This virtual folder gives users access to their own INI files. In addition, Terminal Server makes some adjustments to the registry for a legacy application. These modifications slow the loading of the legacy application on Terminal Server. -If an application is Terminal Server aware, it must neither rely on INI files nor write to the **HKEY_CURRENT_USER** registry during setup. +If an application is Terminal Server aware, it must not rely on INI files or write to the `HKEY_CURRENT_USER` registry during setup. -If you use /TSAWARE and your application still uses INI files, the files will be shared by all users of the system. If that is acceptable, you can still link your application with /TSAWARE; otherwise you need to use /TSAWARE:NO. +If you use **`/TSAWARE`** and your application still uses INI files, the files will be shared by all users of the system. If that's acceptable, you can still link your application with **`/TSAWARE`**; otherwise you need to use **`/TSAWARE:NO`**. -The /TSAWARE option is enabled by default for Windows and console applications. See [/SUBSYSTEM](subsystem-specify-subsystem.md) and [/VERSION](version-version-information.md) for information. +The **`/TSAWARE`** option is enabled by default for Windows and console applications. For more information, see [`/SUBSYSTEM`](subsystem-specify-subsystem.md) and [`/VERSION`](version-version-information.md). -/TSAWARE is not valid for drivers or DLLs. +**`/TSAWARE`** isn't valid for drivers or DLLs. -If an application was linked with /TSAWARE, DUMPBIN [/HEADERS](headers.md) will display information to that effect. +If an application was linked with **`/TSAWARE`**, [`DUMPBIN /HEADERS`](headers.md) will display information to that effect. ### To set this linker option in the Visual Studio development environment diff --git a/docs/build/reference/version-version-information.md b/docs/build/reference/version-version-information.md index 9d3cbf2c2ce..d4ab8a430ec 100644 --- a/docs/build/reference/version-version-information.md +++ b/docs/build/reference/version-version-information.md @@ -1,31 +1,29 @@ --- -description: "Learn more about: /VERSION (Version Information)" -title: "/VERSION (Version Information)" -ms.date: "11/04/2016" +description: "Learn more about: /VERSION (Version information)" +title: "/VERSION (Version information)" +ms.date: 03/02/2022 f1_keywords: ["VC.Project.VCLinkerTool.Version", "/version"] helpviewer_keywords: ["-VERSION linker option", "Version Information linker option", "version numbers, specifying in .exe", "/VERSION linker option", "VERSION linker option"] ms.assetid: b86d0e86-dca6-4316-aee2-d863ccb9f223 --- -# /VERSION (Version Information) +# `/VERSION` (Version information) -``` -/VERSION:major[.minor] -``` +> **`/VERSION:`***`major`*\[*`.minor`*] ## Arguments -*major* and *minor*
-The version number you want in the header of the .exe or .dll file. +*`major`* and *`minor`*
+The version number you want in the header of the EXE or DLL file. ## Remarks -The /VERSION option tells the linker to put a version number in the header of the .exe or .dll file. Use DUMPBIN [/HEADERS](headers.md) to see the image version field of the OPTIONAL HEADER VALUES to see the effect of /VERSION. +The **`/VERSION`** option tells the linker to put a version number in the header of the EXE or DLL file. Use [`DUMPBIN /HEADERS`](headers.md) to see the image version field of the `OPTIONAL HEADER VALUES` to see the effect of **`/VERSION`**. -The *major* and *minor* arguments are decimal numbers in the range 0 through 65,535. The default is version 0.0. +The *`major`* and *`minor`* arguments are decimal numbers in the range 0 through 65,535. The default is version `0.0`. -The information specified with /VERSION does not affect the version information that appears for an application when you view its properties in File Explorer. That version information comes from a resource file that is used to build the application. See [Version Information Editor](../../windows/version-information-editor.md) for more information. +The information specified with **`/VERSION`** doesn't affect the version information that appears for an application when you view its properties in File Explorer. That version information comes from a resource file that's used to build the application. For more information, see [Version Information Editor](../../windows/version-information-editor.md). -Another way to insert a version number is with the [VERSION](version-c-cpp.md) module-definition statement. +Another way to insert a version number is with the [`VERSION`](version-c-cpp.md) module-definition statement. ### To set this linker option in the Visual Studio development environment @@ -41,5 +39,5 @@ Another way to insert a version number is with the [VERSION](version-c-cpp.md) m ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/xml-document-generator-tool-property-pages.md b/docs/build/reference/xml-document-generator-tool-property-pages.md index 44c2fc716ef..ddcf002fcab 100644 --- a/docs/build/reference/xml-document-generator-tool-property-pages.md +++ b/docs/build/reference/xml-document-generator-tool-property-pages.md @@ -1,16 +1,16 @@ --- description: "Learn more about: XML Document Generator Tool Property Pages" title: "XML Document Generator Tool Property Pages" -ms.date: "11/04/2016" +ms.date: 03/02/2022 f1_keywords: ["VC.Project.VCXDCMakeTool.ValidateIntelliSense", "VC.Project.VCXDCMakeTool.SuppressStartupBanner", "VC.Project.VCXDCMakeTool.DocumentLibraryDependencies", "VC.Project.VCXDCMakeTool.OutputDocumentFile", "VC.Project.VCXDCMakeTool.AdditionalDocumentFiles"] ms.assetid: 645912b5-197a-4c36-ba58-64df09444ca0 --- # XML Document Generator Tool Property Pages -The XML Document Generator Tool property page exposes the functionality of xdcmake.exe. xdcmake.exe merges .xdc files into an .xml file when your source code contains documentation comments and [/doc (Process Documentation Comments) (C/C++)](doc-process-documentation-comments-c-cpp.md) is specified,. See [Recommended Tags for Documentation Comments](recommended-tags-for-documentation-comments-visual-cpp.md) for information on adding documentation comments to source code. +The XML Document Generator Tool property page exposes the functionality of *`xdcmake.exe`*, or XDCMake. XDCMake merges *`.xdc`* files into an *`.xml`* file when your source code contains documentation comments and [`/doc` (Process Documentation Comments) (C/C++)](doc-process-documentation-comments-c-cpp.md) is specified. For more information on adding documentation comments to source code, see [Recommended tags for documentation comments](recommended-tags-for-documentation-comments-visual-cpp.md). > [!NOTE] -> xdcmake.exe options in the development environment (property pages) differ from the options when xdcmake.exe is used at the command line. For information on using xdcmake.exe at the command line, see [XDCMake Reference](xdcmake-reference.md). +> XDCMake options in the development environment (property pages) differ from the options when *`xdcmake.exe`* is used at the command line. For information on using *`xdcmake.exe`* at the command line, see [XDCMake reference](xdcmake-reference.md). ## UIElement List @@ -20,15 +20,15 @@ The XML Document Generator Tool property page exposes the functionality of xdcma - **Additional Document Files** - Additional directories in which you want the project system to look for .xdc files. xdcmake will always look for .xdc files generated by the project. Multiple directories can be specified. + Additional directories in which you want the project system to look for *`.xdc`* files. XDCMake always looks for *`.xdc`* files generated by the project. Multiple directories can be specified. - **Output Document File** - The name and directory location of the .xml output file. See [Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md) for information on using macros to specify directory locations. + The name and directory location of the *`.xml`* output file. For more information on using macros to specify directory locations, see [Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md). - **Document Library Dependencies** - If your project has a dependency on a .lib project in the solution, you can process .xdc files from the .lib project into the .xml files for the current project. + If your project has a dependency on a *`.lib`* project in the solution, you can process *`.xdc`* files from the *`.lib`* project into the *`.xml`* files for the current project. ## See also diff --git a/docs/code-quality/c26813.md b/docs/code-quality/c26813.md new file mode 100644 index 00000000000..76618ca09e1 --- /dev/null +++ b/docs/code-quality/c26813.md @@ -0,0 +1,45 @@ +--- +description: "Learn more about: C26813" +title: c26813 +ms.date: 03/02/2022 +ms.topic: reference +f1_keywords: ["C26813"] +helpviewer_keywords: ["C26813"] +--- +# C26813 + +> Warning C26813: Use 'bitwise and' to check if a flag is set + +Most `enum` types with power of two member values are intended to be used as bit flags. As a result, you rarely want to compare these flags for equality. Instead, extract the bits you're interested in by using bitwise operations. + +## Example + +```cpp +enum BitWise +{ + A = 1, + B = 2, + C = 4 +}; + +void useEqualsWithBitwiseEnum(BitWise a) +{ + if (a == B) // Warning C26813: Use 'bitwise and' to check if a flag is set + return; +} +``` + +To fix the warning, use bitwise operations: + +```cpp +void useEqualsWithBitwiseEnum(BitWise a) +{ + if (a & B) // Fixed. + return; +} +``` + +## See also + +[C26827](./c26827.md)\ +[C26828](./c26828.md) diff --git a/docs/code-quality/c26827.md b/docs/code-quality/c26827.md new file mode 100644 index 00000000000..2d8b5475a64 --- /dev/null +++ b/docs/code-quality/c26827.md @@ -0,0 +1,52 @@ +--- +description: "Learn more about: C26827" +title: c26827 +ms.date: 03/02/2022 +ms.topic: reference +f1_keywords: ["C26827"] +helpviewer_keywords: ["C26827"] +--- +# C26827 + +> Warning C26827: Did you forget to initialize an enum, or intend to use another type? + +Most `enum` types used in bitwise operations are expected to have members with values of powers of two. This warning attempts to find cases where a value wasn't given explicitly to an enumeration constant. It also finds cases where the wrong enumeration type may have been used inadvertently. + +## Example + +```cpp +enum class AlmostBitWise +{ + A = 1, + B = 2, + C = 4, + D +}; + +int almostBitwiseEnums(AlmostBitWise a, bool cond) +{ + return (int)a|(int)AlmostBitWise::A; // Warning C26827: Did you forget to initialize an enum, or intend to use another type? +} +``` + +To fix the warning, initialize the enumeration constant to the correct value, or use the correct enumeration type in the operation. + +```cpp +enum class AlmostBitWise +{ + A = 1, + B = 2, + C = 4, + D = 8 +}; + +int almostBitwiseEnums(AlmostBitWise a, bool cond) +{ + return (int)a|(int)AlmostBitWise::A; // No warning. +} +``` + +## See also + +[C26813](./c26813.md)\ +[C26828](./c26828.md) diff --git a/docs/code-quality/c26828.md b/docs/code-quality/c26828.md new file mode 100644 index 00000000000..34eef90fec0 --- /dev/null +++ b/docs/code-quality/c26828.md @@ -0,0 +1,60 @@ +--- +description: "Learn more about: C26828" +title: c26828 +ms.date: 03/02/2022 +ms.topic: reference +f1_keywords: ["C26828"] +helpviewer_keywords: ["C26828"] +--- +# C26828 + +> Warning C26828: Different enum types have overlapping values. Did you want to use another enum constant here? + +Most of the time, a single enumeration type describes all the bit flags that you can use for an option. If you use two different enumeration types that have overlapping values in the same bitwise expression, the chances are good those enumeration types weren't designed for use together. + +## Example + +```cpp + +enum BitWiseA +{ + A = 1, + B = 2, + C = 4 +}; + +enum class BitWiseB +{ + AA = 1, + BB = 2, + CC = 4, + All = 7 +}; + +int overlappingBitwiseEnums(BitWiseA a) +{ + return (int)a|(int)BitWiseB::AA; // Warning C26828: Different enum types have overlapping values. Did you want to use another enum constant here? +} +``` + +To fix the warning, make sure enumeration types designed for use together have no overlapping values. Or, make sure all the related options are in a single enumeration type. + +```cpp + +enum BitWiseA +{ + A = 1, + B = 2, + C = 4 +}; + +int overlappingBitwiseEnums(BitWiseA a) +{ + return (int)a|(int)BitWiseA::A; // No warning. +} +``` + +## See also + +[C26813](./c26813.md)\ +[C26827](./c26827.md) diff --git a/docs/code-quality/toc.yml b/docs/code-quality/toc.yml index d487a2fd3d6..e2ccc86bd1c 100644 --- a/docs/code-quality/toc.yml +++ b/docs/code-quality/toc.yml @@ -579,8 +579,14 @@ items: href: ../code-quality/c26810.md - name: C26811 href: ../code-quality/c26811.md + - name: C26813 + href: ../code-quality/c26813.md - name: C26826 href: ../code-quality/c26826.md + - name: C26827 + href: ../code-quality/c26827.md + - name: C26828 + href: ../code-quality/c26828.md - name: C28020 href: ../code-quality/c28020.md - name: C28021 diff --git a/docs/standard-library/basic-string-view-class.md b/docs/standard-library/basic-string-view-class.md index 6d7f39b552c..b2e31912c4f 100644 --- a/docs/standard-library/basic-string-view-class.md +++ b/docs/standard-library/basic-string-view-class.md @@ -4,9 +4,8 @@ description: "API reference for `basic_string_view` which refers to a constant c ms.date: "9/8/2020" f1_keywords: ["xstring/std::basic_string_view", "xstring/std::basic_string_view::allocator_type", "xstring/std::basic_string_view::const_iterator", "xstring/std::basic_string_view::const_pointer", "xstring/std::basic_string_view::const_reference", "xstring/std::basic_string_view::const_reverse_iterator", "xstring/std::basic_string_view::difference_type", "xstring/std::basic_string_view::ends_with", "xstring/std::basic_string_view::starts_with", "xstring/std::basic_string_view::iterator", "xstring/std::basic_string_view::npos", "xstring/std::basic_string_view::pointer", "xstring/std::basic_string_view::reference", "xstring/std::basic_string_view::reverse_iterator", "xstring/std::basic_string_view::size_type", "xstring/std::basic_string_view::traits_type", "xstring/std::basic_string_view::value_type", "xstring/std::basic_string_view::append", "xstring/std::basic_string_view::assign", "xstring/std::basic_string_view::at", "xstring/std::basic_string_view::back", "xstring/std::basic_string_view::begin", "xstring/std::basic_string_view::c_str", "xstring/std::basic_string_view::capacity", "xstring/std::basic_string_view::cbegin", "xstring/std::basic_string_view::cend", "xstring/std::basic_string_view::clear", "xstring/std::basic_string_view::compare", "xstring/std::basic_string_view::copy", "xstring/std::basic_string_view::_Copy_s", "xstring/std::basic_string_view::crbegin", "xstring/std::basic_string_view::crend", "xstring/std::basic_string_view::data", "xstring/std::basic_string_view::empty", "xstring/std::basic_string_view::end", "xstring/std::basic_string_view::erase", "xstring/std::basic_string_view::find", "xstring/std::basic_string_view::find_first_not_of", "xstring/std::basic_string_view::find_first_of", "xstring/std::basic_string_view::find_last_not_of", "xstring/std::basic_string_view::find_last_of", "xstring/std::basic_string_view::front", "xstring/std::basic_string_view::get_allocator", "xstring/std::basic_string_view::insert", "xstring/std::basic_string_view::length", "xstring/std::basic_string_view::max_size", "xstring/std::basic_string_view::pop_back", "xstring/std::basic_string_view::push_back", "xstring/std::basic_string_view::rbegin", "xstring/std::basic_string_view::rend", "xstring/std::basic_string_view::remove_prefix","xstring/std::basic_string_view::remove_suffix", "xstring/std::basic_string_view::replace", "xstring/std::basic_string_view::reserve", "xstring/std::basic_string_view::resize", "xstring/std::basic_string_view::rfind", "xstring/std::basic_string_view::shrink_to_fit", "xstring/std::basic_string_view::size", "xstring/std::basic_string_view::substr", "xstring/std::basic_string_view::swap"] helpviewer_keywords: ["std::basic_string_view", "std::basic_string_view, allocator_type", "std::basic_string_view, const_iterator", "std::basic_string_view, const_pointer", "std::basic_string_view, const_reference", "std::basic_string_view, const_reverse_iterator", "std::basic_string_view, difference_type", "std::basic_string_view, iterator", "std::basic_string_view, npos", "std::basic_string_view, pointer", "std::basic_string_view, reference", "std::basic_string_view, reverse_iterator", "std::basic_string_view, size_type", "std::basic_string_view, traits_type", "std::basic_string_view, value_type", "std::basic_string_view, append", "std::basic_string_view, assign", "std::basic_string_view, at", "std::basic_string_view, back", "std::basic_string_view, begin", "std::basic_string_view, c_str", "std::basic_string_view, capacity", "std::basic_string_view, cbegin", "std::basic_string_view, cend", "std::basic_string_view, clear", "std::basic_string_view, compare", "std::basic_string_view, copy", "std::basic_string_view, crbegin", "std::basic_string_view, crend", "std::basic_string_view, data", "std::basic_string_view, empty", "std::basic_string_view, end", "std::basic_string_view, ends_with", "std::basic_string_view, erase", "std::basic_string_view, find", "std::basic_string_view, find_first_not_of", "std::basic_string_view, find_first_of", "std::basic_string_view, find_last_not_of", "std::basic_string_view, find_last_of", "std::basic_string_view, front", "std::basic_string_view, get_allocator", "std::basic_string_view, insert", "std::basic_string_view, length", "std::basic_string_view, max_size", "std::basic_string_view, pop_back", "std::basic_string_view, push_back", "std::basic_string_view, rbegin", "std::basic_string_view, rend", "std::basic_string_view, remove_prefix","std::basic_string_view, remove_suffix","std::basic_string_view, replace", "std::basic_string_view, reserve", "std::basic_string_view, resize", "std::basic_string_view, rfind", "std::basic_string_view, shrink_to_fit", "std::basic_string_view, size", "std::basic_string_view, starts_with", "std::basic_string_view, substr", "std::basic_string_view, swap"] -ms.assetid: a9c3e0a2-39bf-4c8a-b093-9abe30839591 --- -# basic_string_view Class +# `basic_string_view` Class The class template `basic_string_view` was added in C++17 to serve as a safe and efficient way for a function to accept various unrelated string types without the function having to be templatized on those types. The class holds a non-owning pointer to a contiguous sequence of character data, and a length that specifies the number of characters in the sequence. No assumption is made with respect to whether the sequence is null-terminated. @@ -17,11 +16,9 @@ The standard library defines several specializations based on the type of the el - `u16string_view` - `u32string_view` -In this document, the term "string_view" refers generally to any of these typedefs. +A `basic_string_view` describes the minimum common interface necessary to read string data. It provides const access to the underlying data; it makes no copies (except for the `copy` function). The data may or may not contain null values (`\0`) at any position. A `basic_string_view` has no control over the object's lifetime. It's the caller's responsibility to ensure that the underlying string data is valid. -A string_view describes the minimum common interface necessary to read string data. It provides const access to the underlying data; it makes no copies (except for the `copy` function). The data may or may not contain null values ('\0') at any position. A string_view has no control over the object's lifetime. It's the caller's responsibility to ensure that the underlying string data is valid. - -A function that accepts a parameter of type string_view can be made to work with any string-like type, without making the function into a template, or constraining the function to a particular subset of string types. The only requirement is that an implicit conversion exists from the string type to string_view. All the standard string types are implicitly convertible to a string_view that contains the same element type. In other words, a `std::string` is convertible to a `string_view` but not to a `wstring_view`. +A function that accepts a parameter of type `string_view` can be made to work with any string-like type, without making the function into a template, or constraining the function to a particular subset of string types. The only requirement is that an implicit conversion exists from the string type to `string_view`. All the standard string types are implicitly convertible to a `string_view` that contains the same element type. In other words, a `std::string` is convertible to a `string_view` but not to a `wstring_view`. The following example shows a non-template function `f` that takes a parameter of type `wstring_view`. It can be called with arguments of type `std::wstring`, `wchar_t*`, and `winrt::hstring`. @@ -57,99 +54,99 @@ class basic_string_view; ### Parameters -*CharType*\ -The type of the characters that are stored in the string_view. The C++ Standard Library provides the following typedefs for specializations of this template. +*`CharType`*\ +The type of the characters that are stored in the `basic_string_view`. The C++ Standard Library provides the following typedefs for specializations of this template. -- [string_view](../standard-library/string-view-typedefs.md#string_view) for elements of type **`char`** -- [wstring_view](../standard-library/string-view-typedefs.md#wstring_view), for **`wchar_t`** -- [u16string_view](../standard-library/string-view-typedefs.md#u16string_view) for **`char16_t`** -- [u32string_view](../standard-library/string-view-typedefs.md#u32string_view) for **`char32_t`**. +- [`string_view`](../standard-library/string-view-typedefs.md#string_view) for elements of type **`char`** +- [`wstring_view`](../standard-library/string-view-typedefs.md#wstring_view), for **`wchar_t`** +- [`u16string_view`](../standard-library/string-view-typedefs.md#u16string_view) for **`char16_t`** +- [`u32string_view`](../standard-library/string-view-typedefs.md#u32string_view) for **`char32_t`**. -*Traits*\ -Defaults to [char_traits](char-traits-struct.md)<*CharType*>. +*`Traits`*\ +Defaults to [`char_traits`](char-traits-struct.md)<*`CharType`*>. ### Constructors |Constructor|Description| |-|-| -|[basic_string_view](#basic_string_view)|Constructs a string_view that is empty or else points to all or part of some other string object's data, or to a C-style character array.| +|[`basic_string_view`](#basic_string_view)|Constructs a `basic_string_view` that is empty or else points to all or part of some other string object's data, or to a C-style character array.| ### Typedefs |Type name|Description| |-|-| -|**const_iterator**|Random-access iterator that can read **`const`** elements.| -|**const_pointer**|`using const_pointer = const value_type*;`| -|**const_reference**|`using const_reference = const value_type&;`| -|**const_reverse_iterator**|`using const_reverse_iterator = std::reverse_iterator;`| -|**difference_type**|`using difference_type = ptrdiff_t;`| -|**iterator**|`using iterator = const_iterator;`| -|**npos**|`static constexpr size_type npos = size_type(-1);`| -|**pointer**|`using pointer = value_type*;`| -|**reference**|`using reference = value_type&;`| -|**reverse_iterator**|`using reverse_iterator = const_reverse_iterator;`| -|**size_type**|`using size_type = size_t;`| -|**traits_type**|`using traits_type = Traits;`| -|**value_type**|`using value_type = CharType;`| +|**`const_iterator`**|Random-access iterator that can read **`const`** elements.| +|**`const_pointer`**|`using const_pointer = const value_type*;`| +|**`const_reference`**|`using const_reference = const value_type&;`| +|**`const_reverse_iterator`**|`using const_reverse_iterator = std::reverse_iterator;`| +|**`difference_type`**|`using difference_type = ptrdiff_t;`| +|**`iterator`**|`using iterator = const_iterator;`| +|**`npos`**|`static constexpr size_type npos = size_type(-1);`| +|**`pointer`**|`using pointer = value_type*;`| +|**`reference`**|`using reference = value_type&;`| +|**`reverse_iterator`**|`using reverse_iterator = const_reverse_iterator;`| +|**`size_type`**|`using size_type = size_t;`| +|**`traits_type`**|`using traits_type = Traits;`| +|**`value_type`**|`using value_type = CharType;`| ### Member operators |Operator|Description| |-|-| -|[operator=](#op_eq)|Assigns a string_view or convertible string object to another string_view.| -|[operator\[\]](#op_at)|Returns the element at the specified index.| +|[`operator=`](#op_eq)|Assigns a `basic_string_view` or convertible string object to another `basic_string_view`.| +|[`operator[]`](#op_at)|Returns the element at the specified index.| ### Member functions |Member function|Description| |-|-| -|[at](#at)|Returns a const_reference to the element at a specified location.| -|[back](#back)|Returns a const_reference to the last element.| -|[begin](#begin)|Returns a const iterator addressing the first element. (string_views are immutable.)| -|[cbegin](#cbegin)|Same as [begin](#begin).| -|[cend](#cend)|Returns a const iterator that points to one past the last element.| -|[copy](#copy)|Copies at most a specified number of characters from an indexed position in a source string_view to a target character array. (Not recommended. Use _Copy_s instead.)| -|[_Copy_s](#_copy_s)|Secure CRT copy function.| -|[compare](#compare)|Compares a string_view with a specified string_view to determine if they're equal or if one is lexicographically less than the other.| -|[crbegin](#crbegin)|Same as [rbegin](#rbegin).| -|[crend](#crend)|Same as [rend](#rend).| -|[data](#data)|Returns a raw non-owning pointer to the character sequence.| -|[empty](#empty)|Tests whether the string_view contains characters.| -|[end](#end)|Same as [cend](#cend).| -|[ends_with](#ends_with)C++20|Check whether a string view ends with a specified suffix.| -|[find](#find)|Searches in a forward direction for the first occurrence of a substring that matches a specified sequence of characters.| -|[find_first_not_of](#find_first_not_of)|Searches for the first character that is not any element of a specified string_view or convertible string object.| -|[find_first_of](#find_first_of)|Searches for the first character that matches any element of a specified string_view or convertible string object.| -|[find_last_not_of](#find_last_not_of)|Searches for the last character that is not any element of a specified string_view or convertible string object.| -|[find_last_of](#find_last_of)|Searches for the last character that is an element of a specified string_view or convertible string object.| -|[front](#front)|Returns a const_reference to the first element.| -|[length](#length)|Returns the current number of elements.| -|[max_size](#max_size)|Returns the maximum number of characters a string_view could contain.| -|[rbegin](#rbegin)|Returns a const iterator that addresses the first element in a reversed string_view.| -|[remove_prefix](#remove_prefix)|Moves the pointer forward by the specified number of elements.| -|[remove_suffix](#remove_suffix)|Reduces the size of the view by the specified number of elements starting from the back.| -|[rend](#rend)|Returns a const iterator that points to one past the last element in a reversed string_view.| -|[rfind](#rfind)|Searches a string_view in reverse for the first occurrence of a substring that matches a specified sequence of characters.| -|[size](#size)|Returns the current number of elements.| -|[starts_with](#starts_with)C++20|Check whether a string view starts with a given prefix.| -|[substr](#substr)|Returns a substring of a specified length starting at a specified index.| -|[swap](#swap)|Exchange the contents of two string_views.| +|[`at`](#at)|Returns a `const_reference` to the element at a specified location.| +|[`back`](#back)|Returns a `const_reference` to the last element.| +|[`begin`](#begin)|Returns a `const` iterator addressing the first element. (`basic_string_view`s are immutable.)| +|[`cbegin`](#cbegin)|Same as [`begin`](#begin).| +|[`cend`](#cend)|Returns a `const` iterator that points to one past the last element.| +|[`copy`](#copy)|Copies at most a specified number of characters from an indexed position in a source `basic_string_view` to a target character array. (Not recommended. Use `_Copy_s` instead.)| +|[`_Copy_s`](#_copy_s)|Secure CRT copy function.| +|[`compare`](#compare)|Compares a `basic_string_view` with a specified `basic_string_view` to determine if they're equal or if one is lexicographically less than the other.| +|[`crbegin`](#crbegin)|Same as [`rbegin`](#rbegin).| +|[`crend`](#crend)|Same as [`rend`](#rend).| +|[`data`](#data)|Returns a raw non-owning pointer to the character sequence.| +|[`empty`](#empty)|Tests whether the `basic_string_view` contains characters.| +|[`end`](#end)|Same as [`cend`](#cend).| +|[`ends_with`](#ends_with)C++20|Check whether a string view ends with a specified suffix.| +|[`find`](#find)|Searches in a forward direction for the first occurrence of a substring that matches a specified sequence of characters.| +|[`find_first_not_of`](#find_first_not_of)|Searches for the first character that isn't any element of a specified `basic_string_view` or convertible string object.| +|[`find_first_of`](#find_first_of)|Searches for the first character that matches any element of a specified `basic_string_view` or convertible string object.| +|[`find_last_not_of`](#find_last_not_of)|Searches for the last character that isn't any element of a specified `basic_string_view` or convertible string object.| +|[`find_last_of`](#find_last_of)|Searches for the last character that is an element of a specified `basic_string_view` or convertible string object.| +|[`front`](#front)|Returns a `const_reference` to the first element.| +|[`length`](#length)|Returns the current number of elements.| +|[`max_size`](#max_size)|Returns the maximum number of characters a `basic_string_view` could contain.| +|[`rbegin`](#rbegin)|Returns a `const` iterator that addresses the first element in a reversed `basic_string_view`.| +|[`remove_prefix`](#remove_prefix)|Moves the pointer forward by the specified number of elements.| +|[`remove_suffix`](#remove_suffix)|Reduces the size of the view by the specified number of elements starting from the back.| +|[`rend`](#rend)|Returns a `const` iterator that points to one past the last element in a reversed `basic_string_view`.| +|[`rfind`](#rfind)|Searches a `basic_string_view` in reverse for the first occurrence of a substring that matches a specified sequence of characters.| +|[`size`](#size)|Returns the current number of elements.| +|[`starts_with`](#starts_with)C++20|Check whether a string view starts with a given prefix.| +|[`substr`](#substr)|Returns a substring of a specified length starting at a specified index.| +|[`swap`](#swap)|Exchange the contents of two `basic_string_view` objects.| ## Remarks -If a function is asked to generate a sequence longer than [max_size](#max_size) elements, the function reports a length error by throwing an object of type [length_error](../standard-library/length-error-class.md). +If a function is asked to generate a sequence longer than [`max_size`](#max_size) elements, the function reports a length error by throwing an object of type [`length_error`](../standard-library/length-error-class.md). ## Requirements [`std:c++17`](../build/reference/std-specify-language-standard-version.md) or later. -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` -## basic_string_view::at +## `basic_string_view::at` -Returns a const_reference to the character at the specified 0-based index. +Returns a `const_reference` to the character at the specified 0-based index. ```cpp constexpr const_reference at(size_type offset) const; @@ -157,20 +154,20 @@ constexpr const_reference at(size_type offset) const; ### Parameters -*offset*\ +*`offset`*\ The index of the element to be referenced. ### Return Value -A const_reference to the character at the position specified by the parameter index. +A `const_reference` to the character at the position specified by the parameter index. ### Remarks -The first element has an index of zero and the following elements are indexed consecutively by the positive integers, so that a string_view of length *n* has an *n*th element indexed by the number *n -* 1. **at** throws an exception for invalid indices, unlike [operator\[\]](#op_at). +The first element has an index of zero and the following elements are indexed consecutively by the positive integers, so that a `basic_string_view` of length *`n`* has an *`n`*th element indexed by the number `n - 1`. **`at`** throws an exception for invalid indices, unlike [`operator[]`](#op_at). -In general, we recommend that **at** for sequences such as `std::vector` and string_view should never be used. An invalid index passed to a sequence is a logic error that should be discovered and fixed during development. If a program isn't certain that its indices are valid, it should test them, not call at() and rely on exceptions to defend against careless programming. +In general, we recommend that **`at`** for sequences such as `std::vector` and `basic_string_view` should never be used. An invalid index passed to a sequence is a logic error that should be discovered and fixed during development. If a program isn't certain that its indices are valid, it should test them, not call `at()` and rely on exceptions to defend against careless programming. -See [basic_string_view::operator\[\]](#op_at) for more information. +See [`basic_string_view::operator[]`](#op_at) for more information. ### Example @@ -189,9 +186,9 @@ int main() } ``` -## basic_string_view::back +## `basic_string_view::back` -Returns a const_reference to the last element. +Returns a `const_reference` to the last element. ```cpp constexpr const_reference back() const; @@ -199,17 +196,17 @@ constexpr const_reference back() const; ### Return Value -A const_reference to the last element in the string_view. +A `const_reference` to the last element in the `basic_string_view`. ### Remarks -Throws an exception if the string_view is empty. +Throws an exception if the `basic_string_view` is empty. -Keep in mind that after a string_view is modified, for example by calling `remove_suffix`, then the element returned by this function is no longer the last element in the underlying data. +Keep in mind that after a `basic_string_view` is modified, for example by calling `remove_suffix`, then the element returned by this function is no longer the last element in the underlying data. ### Example -A `string_view` that is constructed with a C string literal does not include the terminating null. So in the following example, `back` returns `'p'` and not `'\0'`. +A `string_view` that is constructed with a C string literal doesn't include the terminating null. So in the following example, `back` returns `'p'` and not `'\0'`. ```cpp char c[] = "Help"; // char[5] @@ -225,9 +222,9 @@ string_view e = "embedded\0nulls"sv; cout << boolalpha << (e.back() == 's'); // true ``` -## basic_string_view::basic_string_view +## `basic_string_view::basic_string_view` -Constructs a string_view. +Constructs a `basic_string_view`. ```cpp constexpr basic_string_view() noexcept; @@ -238,21 +235,21 @@ constexpr basic_string_view(const charT* str, size_type len); ### Parameters -*str*\ +*`str`*\ The pointer to the character values. -*len*\ +*`len`*\ The number of characters to include in the view. ### Remarks -The constructors with a charT* parameter assume that the input is null-terminated, but the terminating null is not included in the string_view. +The constructors with a `charT*` parameter assume that the input is null-terminated, but the terminating null isn't included in the `basic_string_view`. -You can also construct a string_view with a literal. See [operator""sv](string-view-operators.md#op_sv). +You can also construct a `basic_string_view` with a literal. See [`operator"" sv`](string-view-operators.md#op_sv). -## basic_string_view::begin +## `basic_string_view::begin` -Same as [cbegin](#cbegin). +Same as [`cbegin`](#cbegin). ```cpp constexpr const_iterator begin() const noexcept; @@ -260,11 +257,11 @@ constexpr const_iterator begin() const noexcept; ### Return Value -Returns a const_iterator addressing the first element. +Returns a `const_iterator` addressing the first element. -## basic_string_view::cbegin +## `basic_string_view::cbegin` -Returns a const_iterator that addresses the first element in the range. +Returns a `const_iterator` that addresses the first element in the range. ```cpp constexpr const_iterator cbegin() const noexcept; @@ -274,9 +271,9 @@ constexpr const_iterator cbegin() const noexcept; A **`const`** random-access iterator that points at the first element of the range, or the location just beyond the end of an empty range (for an empty range, `cbegin() == cend()`). -## basic_string_view::cend +## `basic_string_view::cend` -Returns a const_iterator that addresses the location just beyond the last element in a range. +Returns a `const_iterator` that addresses the location just beyond the last element in a range. ```cpp constexpr const_iterator cend() const noexcept; @@ -290,9 +287,9 @@ A **`const`** random-access iterator that points just beyond the end of the rang The value returned by `cend` shouldn't be dereferenced. -## basic_string_view::compare +## `basic_string_view::compare` -Does a case-sensitive comparison with a specified string_view (or a convertible string type) to determine if the two objects are equal or if one is lexicographically less than the other. The [\ operators](string-view-operators.md) use this member function to do comparisons. +Does a case-sensitive comparison with a specified `basic_string_view` (or a convertible string type) to determine if the two objects are equal or if one is lexicographically less than the other. The [`` operators](string-view-operators.md) use this member function to do comparisons. ```cpp constexpr int compare(basic_string_view strv) const noexcept; @@ -305,29 +302,29 @@ constexpr int compare(size_type pos, size_type num, const charT* ptr, size_type ### Parameters -*strv*\ -The string_view that is to be compared to this string_view. +*`strv`*\ +The `basic_string_view` that is to be compared to this `basic_string_view`. -*pos*\ -The index of this string_view at which the comparison begins. +*`pos`*\ +The index of this `basic_string_view` at which the comparison begins. -*num*\ -The maximum number of characters from this string_view to be compared. +*`num`*\ +The maximum number of characters from this `basic_string_view` to be compared. -*num2*\ -The maximum number of characters from *strv* to be compared. +*`num2`*\ +The maximum number of characters from *`strv`* to be compared. -*offset*\ -The index of *strv* at which the comparison begins. +*`offset`*\ +The index of *`strv`* at which the comparison begins. -*ptr*\ -The C string to be compared to this string_view. +*`ptr`*\ +The C string to be compared to this `basic_string_view`. ### Return Value -- A negative value if this `string_view` is less than *strv* or *ptr* +- A negative value if this `basic_string_view` is less than *`strv`* or *`ptr`* - Zero if the two character sequences are equal -- A positive value if this `string_view` is greater than *strv* or *ptr* +- A positive value if this `basic_string_view` is greater than *`strv`* or *`ptr`* ### Remarks @@ -441,9 +438,9 @@ cs_C: ACAB The 3 characters from position 1 of sv_I are equal to the first 3 characters of cs_C. ``` -## basic_string_view::copy +## `basic_string_view::copy` -Copies at most a specified number of characters from an indexed position in a source string_view to a target character array. We recommend that you use the secure function [basic_string_view::_Copy_s](#_copy_s) instead. +Copies at most a specified number of characters from an indexed position in a source `basic_string_view` to a target character array. We recommend that you use the secure function [`basic_string_view::_Copy_s`](#_copy_s) instead. ```cpp size_type copy(charT* ptr, size_type count, size_type offset = 0) const; @@ -451,14 +448,14 @@ size_type copy(charT* ptr, size_type count, size_type offset = 0) const; ### Parameters -*ptr*\ +*`ptr`*\ The target character array to which the elements are to be copied. -*count*\ -The number of characters to be copied, at most, from the source string_view. +*`count`*\ +The number of characters to be copied, at most, from the source `basic_string_view`. -*offset*\ -The beginning position in the source string_view from which copies are to be made. +*`offset`*\ +The beginning position in the source `basic_string_view` from which copies are to be made. ### Return Value @@ -466,11 +463,11 @@ The number of characters copied. ### Remarks -A null character is not appended to the end of the copy. +A null character isn't appended to the end of the copy. -## basic_string_view::_Copy_s +## `basic_string_view::_Copy_s` -Secure CRT copy function to be used instead of [copy](#copy). +Secure CRT copy function to be used instead of [`copy`](#copy). ```cpp size_type _Copy_s( @@ -482,16 +479,16 @@ size_type _Copy_s( ### Parameters -*dest*\ +*`dest`*\ The target character array to which the elements are to be copied. -*dest_size*\ -The size of *dest*. +*`dest_size`*\ +The size of *`dest`*. -_ *Count* +*`count`* The number of characters to be copied, at most, from the source string. -*_Off*\ +*`_Off`*\ The beginning position in the source string from which copies are to be made. ### Return Value @@ -500,13 +497,13 @@ The number of characters copied. ### Remarks -A null character is not appended to the end of the copy. +A null character isn't appended to the end of the copy. For more information, see [c-runtime-library/security-features-in-the-crt](../c-runtime-library/security-features-in-the-crt.md). -## basic_string_view::crbegin +## `basic_string_view::crbegin` -Returns a const_reverse_iterator that addresses the first element in a reversed string_view. +Returns a `const_reverse_iterator` that addresses the first element in a reversed `basic_string_view`. ```cpp constexpr const_reverse_iterator crbegin() const noexcept; @@ -514,11 +511,11 @@ constexpr const_reverse_iterator crbegin() const noexcept; ### Return Value -A const_reverse_iterator that addresses the first element in a reversed string_view. +A `const_reverse_iterator` that addresses the first element in a reversed `basic_string_view`. -## basic_string_view::crend +## `basic_string_view::crend` -Same as [rend](#rend). +Same as [`rend`](#rend). ```cpp constexpr const_reverse_iterator crend() const noexcept; @@ -526,11 +523,11 @@ constexpr const_reverse_iterator crend() const noexcept; ### Return Value -Returns a const_reverse_iterator that addresses one past the end of a reversed string_view. +Returns a `const_reverse_iterator` that addresses one past the end of a reversed `basic_string_view`. -## basic_string_view::data +## `basic_string_view::data` -Returns a raw non-owning pointer to the const character sequence of the object that was used to construct the string_view. +Returns a raw non-owning pointer to the const character sequence of the object that was used to construct the `basic_string_view`. ```cpp constexpr value_type *data() const noexcept; @@ -542,13 +539,13 @@ A pointer-to-const to the first element of the character sequence. ### Remarks -The pointer cannot modify the characters. +The pointer can’t modify the characters. -A sequence of string_view characters is not necessarily null-terminated. The return type for `data` is not a valid C string, because no null character gets appended. The null character '\0' has no special meaning in an object of type string_view and may be a part of the string_view object just like any other character. +A sequence of `basic_string_view` characters isn't necessarily null-terminated. The return type for `data` isn't a valid C string, because no null character gets appended. The null character `\0` has no special meaning in an object of type `basic_string_view` and may be a part of the `basic_string_view` object just like any other character. -## basic_string_view::empty +## `basic_string_view::empty` -Tests whether the string_view contains characters or not. +Tests whether the `basic_string_view` contains characters or not. ```cpp constexpr bool empty() const noexcept; @@ -556,15 +553,15 @@ constexpr bool empty() const noexcept; ### Return Value -**`true`** if the string_view object contains no characters; **`false`** if it has at least one character. +**`true`** if the `basic_string_view` object contains no characters; **`false`** if it has at least one character. ### Remarks -The member function is equivalent to [size](#size)() == 0. +The member function is equivalent to [`size`](#size)() == 0. -## basic_string_view::end +## `basic_string_view::end` -Returns a random-access const_iterator that points to one past the last element. +Returns a random-access `const_iterator` that points to one past the last element. ```cpp constexpr const_iterator end() const noexcept; @@ -572,13 +569,13 @@ constexpr const_iterator end() const noexcept; ### Return Value -Returns a random-access const_iterator that points to one past the last element. +Returns a random-access `const_iterator` that points to one past the last element. ### Remarks -`end` is used to test whether a const_iterator has reached the end of its string_view. The value returned by `end` shouldn't be dereferenced. +`end` is used to test whether a `const_iterator` has reached the end of its `basic_string_view`. The value returned by `end` shouldn't be dereferenced. -## basic_string_view::ends_with +## `basic_string_view::ends_with` Check whether the string view ends with the specified suffix. @@ -590,14 +587,14 @@ bool ends_with(const basic_string_view sv) const noexcept; ### Parameters -*c*\ +*`c`*\ The single character suffix to look for. -*sv*\ +*`sv`*\ A string view containing the suffix to look for.\ -You can pass a `std::basic_string`, which converts to a string view. +You can pass a `std::basic_string`, which converts to a `basic_string_view`. -*x*\ +*`x`*\ Null-terminated character string containing the suffix to look for. ### Return Value @@ -608,7 +605,7 @@ Null-terminated character string containing the suffix to look for. `ends_with()` is new in C++20. To use it, specify the [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later compiler option. -See [starts_with](#starts_with) to check if a string view starts with the specified prefix. +See [`starts_with`](#starts_with) to check if a string view starts with the specified prefix. ### Example @@ -636,9 +633,9 @@ false true ``` -## basic_string_view::find +## `basic_string_view::find` -Searches a `string_view` in a forward direction for the first occurrence of a character or substring that matches a specified sequence of character(s). +Searches a `basic_string_view` in a forward direction for the first occurrence of a character or substring that matches a specified sequence of character(s). ```cpp constexpr size_type find(basic_string_view str, size_type offset = 0) const noexcept; @@ -649,28 +646,28 @@ constexpr size_type find(const charT* ptr, size_type offset = 0) const; ### Parameters -*str*\ -The `string_view` for which the member function is to search. +*`str`*\ +The `basic_string_view` for which the member function is to search. -*chVal*\ +*`chVal`*\ The character value for which the member function is to search. -*offset*\ +*`offset`*\ Index at which the search is to begin. -*ptr*\ +*`ptr`*\ The C string for which the member function is to search. -*count*\ -The number of characters in *ptr*, counting forward from the first character. +*`count`*\ +The number of characters in *`ptr`*, counting forward from the first character. ### Return Value The index of the first character of the substring searched for when successful; otherwise `npos`. -## basic_string_view::find_first_not_of +## `basic_string_view::find_first_not_of` -Searches for the first character that is not an element of a specified string_view or convertible string object. +Searches for the first character that isn't an element of a specified `basic_string_view` or convertible string object. ```cpp constexpr size_type find_first_not_of(basic_string_view str, size_type offset = 0) const noexcept; @@ -681,28 +678,28 @@ constexpr size_type find_first_not_of(const charT* ptr, size_type offset = 0) co ### Parameters -*str*\ -The string_view for which the member function is to search. +*`str`*\ +The `basic_string_view` for which the member function is to search. -*chVal*\ +*`chVal`*\ The character value for which the member function is to search. -*offset*\ +*`offset`*\ Index at which the search is to begin. -*ptr*\ +*`ptr`*\ The C string for which the member function is to search. -*count*\ +*`count`*\ The number of characters, counting forward from the first character, in the C string for which the member function is to search. ### Return Value The index of the first character of the substring searched for when successful; otherwise `npos`. -## basic_string_view::find_first_of +## `basic_string_view::find_first_of` -Searches for the first character that matches any element of a specified string_view. +Searches for the first character that matches any element of a specified `basic_string_view`. ```cpp constexpr size_type find_first_of(basic_string_view str, size_type offset = 0) const noexcept; @@ -713,28 +710,28 @@ constexpr size_type find_first_of(const charT* str, size_type offset = 0) const; ### Parameters -*chVal*\ +*`chVal`*\ The character value for which the member function is to search. -*offset*\ +*`offset`*\ Index at which the search is to begin. -*ptr*\ +*`ptr`*\ The C string for which the member function is to search. -*count*\ +*`count`*\ The number of characters, counting forward from the first character, in the C string for which the member function is to search. -*str*\ -The string_view for which the member function is to search. +*`str`*\ +The `basic_string_view` for which the member function is to search. ### Return Value The index of the first character of the substring searched for when successful; otherwise `npos`. -## basic_string_view::find_last_not_of +## `basic_string_view::find_last_not_of` -Searches for the last character that is not any element of a specified string_view. +Searches for the last character that isn't any element of a specified `basic_string_view`. ```cpp constexpr size_type find_last_not_of(basic_string_view str, size_type offset = npos) const noexcept; @@ -745,28 +742,28 @@ constexpr size_type find_last_not_of(const charT* ptr, size_type offset = npos) ### Parameters -*str*\ -The string_view for which the member function is to search. +*`str`*\ +The `basic_string_view` for which the member function is to search. -*chVal*\ +*`chVal`*\ The character value for which the member function is to search. -*offset*\ +*`offset`*\ Index at which the search is to finish. -*ptr*\ +*`ptr`*\ The C string for which the member function is to search. -*count*\ -The number of characters, counting forward from the first character, in *ptr*. +*`count`*\ +The number of characters, counting forward from the first character, in *`ptr`*. ### Return Value The index of the first character of the substring searched for when successful; otherwise `string_view::npos`. -## basic_string_view::find_last_of +## `basic_string_view::find_last_of` -Searches for the last character that matches any element of a specified string_view. +Searches for the last character that matches any element of a specified `basic_string_view`. ```cpp constexpr size_type find_last_of(basic_string_view str, size_type offset = npos) const noexcept; @@ -777,28 +774,28 @@ constexpr size_type find_last_of(const charT* ptr, size_type offset = npos) cons ### Parameters -*str*\ -The string_view for which the member function is to search. +*`str`*\ +The `basic_string_view` for which the member function is to search. -*chVal*\ +*`chVal`*\ The character value for which the member function is to search. -*offset*\ +*`offset`*\ Index at which the search is to finish. -*ptr*\ +*`ptr`*\ The C string for which the member function is to search. -*count*\ +*`count`*\ The number of characters, counting forward from the first character, in the C string for which the member function is to search. ### Return Value The index of the last character of the substring searched for when successful; otherwise `npos`. -## basic_string_view::front +## `basic_string_view::front` -Returns a const_reference to the first element. +Returns a `const_reference` to the first element. ```cpp constexpr const_reference front() const; @@ -806,13 +803,13 @@ constexpr const_reference front() const; ### Return Value -A const_reference to the first element. +A `const_reference` to the first element. ### Remarks -Throws an exception if the string_view is empty. +Throws an exception if the `basic_string_view` is empty. -## basic_string_view::length +## `basic_string_view::length` Returns the current number of elements. @@ -822,11 +819,11 @@ constexpr size_type length() const noexcept; ### Remarks -The member function is the same as [size](#size). +The member function is the same as [`size`](#size). -## basic_string_view::max_size +## `basic_string_view::max_size` -Returns the maximum number of characters a string_view can contain. +Returns the maximum number of characters a `basic_string_view` can contain. ```cpp constexpr size_type max_size() const noexcept; @@ -834,15 +831,15 @@ constexpr size_type max_size() const noexcept; ### Return Value -The maximum number of characters a string_view can contain. +The maximum number of characters a `basic_string_view` can contain. ### Remarks -An exception of type [length_error](../standard-library/length-error-class.md) is thrown when an operation produces a string_view with a length greater than `max_size()`. +An exception of type [`length_error`](../standard-library/length-error-class.md) is thrown when an operation produces a `basic_string_view` with a length greater than `max_size()`. -## basic_string_view::operator= +## `basic_string_view::operator=` -Assigns a string_view or convertible string object to another string_view. +Assigns a `basic_string_view` or convertible string object to another `basic_string_view`. ```cpp constexpr basic_string_view& operator=(const basic_string_view&) noexcept = default; @@ -855,9 +852,9 @@ constexpr basic_string_view& operator=(const basic_string_view&) noexcept = defa string_view s2 = s; ``` -## basic_string_view::operator[] +## `basic_string_view::operator[]` -Provides a const_reference to the character with a specified index. +Provides a `const_reference` to the character with a specified index. ```cpp constexpr const_reference operator[](size_type offset) const; @@ -865,28 +862,28 @@ constexpr const_reference operator[](size_type offset) const; ### Parameters -*offset*\ +*`offset`*\ The index of the element to be referenced. ### Return Value -A const_reference to the character at the position specified by the parameter index. +A `const_reference` to the character at the position specified by the parameter index. ### Remarks -The first element has an index of zero, and the following elements are indexed consecutively by the positive integers, so that a string_view of length *n* has an *n*th element indexed by the number *n* - 1. +The first element has an index of zero, and the following elements are indexed consecutively by the positive integers, so that a `basic_string_view` of length *`n`* has an *`n`*th element indexed by the number `n-1`. -`operator[]` is faster than the member function [at](#at) for providing read access to the elements of a string_view. +`operator[]` is faster than the member function [`at`](#at) for providing read access to the elements of a `basic_string_view`. -`operator[]` does not check whether the index passed as an argument is valid. An invalid index passed to `operator[]` results in undefined behavior. +`operator[]` doesn't check whether the index passed as an argument is valid. An invalid index passed to `operator[]` results in undefined behavior. The reference returned may be invalidated if the underlying string data is modified or deleted by the owning object. -When compiling with [\_ITERATOR\_DEBUG\_LEVEL](../standard-library/iterator-debug-level.md) set to 1 or 2, a runtime error will occur if you attempt to access an element outside the bounds of the string_view. For more information, see [Checked Iterators](../standard-library/checked-iterators.md). +When compiling with [`_ITERATOR_DEBUG_LEVEL`](../standard-library/iterator-debug-level.md) set to 1 or 2, a runtime error will occur if you attempt to access an element outside the bounds of the `basic_string_view`. For more information, see [Checked Iterators](../standard-library/checked-iterators.md). -## basic_string_view::rbegin +## `basic_string_view::rbegin` -Returns a const iterator to the first element in a reversed string_view. +Returns a `const` iterator to the first element in a reversed `basic_string_view`. ```cpp constexpr const_reverse_iterator rbegin() const noexcept; @@ -894,13 +891,13 @@ constexpr const_reverse_iterator rbegin() const noexcept; ### Return Value -Returns a random-access iterator to the first element in a reversed string_view, addressing what would be the last element in the corresponding unreversed string_view. +Returns a random-access iterator to the first element in a reversed `basic_string_view`, addressing what would be the last element in the corresponding unreversed `basic_string_view`. ### Remarks -`rbegin` is used with a reversed string_view just as [begin](#begin) is used with a string_view. `rbegin` can be used to initialize an iteration backwards. +`rbegin` is used with a reversed `basic_string_view` just as [`begin`](#begin) is used with a `basic_string_view`. `rbegin` can be used to initialize an iteration backwards. -## basic_string_view::remove_prefix +## `basic_string_view::remove_prefix` Moves the pointer forward by the specified number of elements. @@ -910,9 +907,9 @@ constexpr void remove_prefix(size_type n); ### Remarks -Leaves the underlying data unchanged. Moves the string_view pointer forward by n elements and sets the private `size` data member to size - n. +Leaves the underlying data unchanged. Moves the `basic_string_view` pointer forward by `n` elements and sets the private `size` data member to `size - n`. -## basic_string_view::remove_suffix +## `basic_string_view::remove_suffix` Reduces the size of the view by the specified number of elements starting from the back. @@ -922,11 +919,11 @@ constexpr void remove_suffix(size_type n); ### Remarks -Leaves the underlying data and the pointer to it unchanged. Sets the private `size` data member to size - n. +Leaves the underlying data and the pointer to it unchanged. Sets the private `size` data member to `size - n`. -## basic_string_view::rend +## `basic_string_view::rend` -Returns a const iterator that points to one past the last element in a reversed string_view. +Returns a `const` iterator that points to one past the last element in a reversed `basic_string_view`. ```cpp constexpr reverse_iterator rend() const noexcept; @@ -934,15 +931,15 @@ constexpr reverse_iterator rend() const noexcept; ### Return Value -A const reverse random-access iterator that points to one past the last element in a reversed string_view. +A `const` reverse random-access iterator that points to one past the last element in a reversed `basic_string_view`. ### Remarks -`rend` is used with a reversed string_view just as [end](#end) is used with a string_view. `rend` can be used to test whether a reverse iterator has reached the end of its string_view. The value returned by `rend` shouldn't be dereferenced. +`rend` is used with a reversed `basic_string_view` just as [`end`](#end) is used with a `basic_string_view`. `rend` can be used to test whether a reverse iterator has reached the end of its `basic_string_view`. The value returned by `rend` shouldn't be dereferenced. -## basic_string_view::rfind +## `basic_string_view::rfind` -Searches a string_view in reverse for a substring that matches a specified sequence of characters. +Searches a `basic_string_view` in reverse for a substring that matches a specified sequence of characters. ```cpp constexpr size_type rfind(basic_string_view str, size_type offset = npos) const noexcept; @@ -953,28 +950,28 @@ constexpr size_type rfind(const charT* ptr, size_type offset = npos) const; ### Parameters -*chVal*\ +*`chVal`*\ The character value for which the member function is to search. -*offset*\ +*`offset`*\ Index at which the search is to begin. -*ptr*\ +*`ptr`*\ The C string for which the member function is to search. -*count*\ +*`count`*\ The number of characters, counting forward from the first character, in the C string for which the member function is to search. -*str*\ -The string_view for which the member function is to search. +*`str`*\ +The `basic_string_view` for which the member function is to search. ### Return Value The index of the first character of the substring when successful; otherwise `npos`. -## basic_string_view::size +## `basic_string_view::size` -Returns the number of elements in the string_view. +Returns the number of elements in the `basic_string_view`. ```cpp constexpr size_type size() const noexcept; @@ -982,13 +979,13 @@ constexpr size_type size() const noexcept; ### Return Value -The length of the string_view. +The length of the `basic_string_view`. ### Remarks -A string_view can modify its length, for example by `remove_prefix` and `remove_suffix`. Because this does not modify the underlying string data, the size of a string_view is not necessarily the size of the underlying data. +A `basic_string_view` can modify its length, for example by `remove_prefix` and `remove_suffix`. Because this doesn't modify the underlying string data, the size of a `basic_string_view` isn't necessarily the size of the underlying data. -## basic_string_view::starts_with +## `basic_string_view::starts_with` Check whether the string view starts with the specified prefix. @@ -1000,14 +997,14 @@ bool starts_with(const basic_string_view sv) const noexcept; ### Parameters -*c*\ +*`c`*\ The single character prefix to look for. -*sv*\ +*`sv`*\ A string view containing the prefix to look for.\ You can pass a `std::basic_string`, which converts to a string view. -*x*\ +*`x`*\ Null-terminated character string containing the prefix to look for. ### Return Value @@ -1016,9 +1013,9 @@ Null-terminated character string containing the prefix to look for. ### Remarks -`starts_with()` is new in C++20. To use it, specify the [/std:c++20](../build/reference/std-specify-language-standard-version.md) or later compiler option. +`starts_with()` is new in C++20. To use it, specify the [`std:c++20`](../build/reference/std-specify-language-standard-version.md) or later compiler option. -See [ends_with](#ends_with) to see if a string ends with a suffix. +See [`ends_with`](#ends_with) to see if a string ends with a suffix. ### Example @@ -1046,9 +1043,9 @@ false true ``` -## basic_string_view::substr +## `basic_string_view::substr` -Returns a string_view that represents (at most) the specified number of characters from a specified position. +Returns a `basic_string_view` that represents (at most) the specified number of characters from a specified position. ```cpp constexpr basic_string_view substr(size_type offset = 0, size_type count = npos) const; @@ -1056,19 +1053,19 @@ constexpr basic_string_view substr(size_type offset = 0, size_type count = npos) ### Parameters -*offset*\ +*`offset`*\ An index locating the element at the position from which the copy is made, with a default value of 0. -*count*\ +*`count`*\ The number of characters to include in the substring, if they're present. ### Return Value -A string_view object that represents the specified subsequence of elements. +A `basic_string_view` object that represents the specified subsequence of elements. -## basic_string_view::swap +## `basic_string_view::swap` -Exchanges two string_views, in other words the pointers to the underlying string data, and the size values. +Exchanges two `basic_string_view`s, in other words the pointers to the underlying string data, and the size values. ```cpp constexpr void swap(basic_string_view& sv) noexcept; @@ -1076,10 +1073,10 @@ constexpr void swap(basic_string_view& sv) noexcept; ### Parameters -*sv*\ -The source string_view whose pointer and size values are to be exchanged with that of the destination string_view. +*`sv`*\ +The source `basic_string_view` whose pointer and size values are to be exchanged with that of the destination `basic_string_view`. ## See also -[\](../standard-library/string-view.md)\ +[``](../standard-library/string-view.md)\ [Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md)