diff --git a/docs/c-runtime-library/crt-library-features.md b/docs/c-runtime-library/crt-library-features.md index e0ec29308ca..d53ee6a7ded 100644 --- a/docs/c-runtime-library/crt-library-features.md +++ b/docs/c-runtime-library/crt-library-features.md @@ -3,6 +3,7 @@ title: "C runtime (CRT) and C++ Standard Library .lib files" description: "List of Microsoft C runtime and C++ Standard Library .lib files that you can link against and their associated compiler options and preprocessor directives." ms.date: "3/5/2021" ms.topic: "reference" +ms.custom: contperf-fy21q3 helpviewer_keywords: ["MSVCR71.dll", "libraries [C++], multithreaded", "library files, run-time", "LIBCMT.lib", "LIBCP.lib", "LIBCPMT.lib", "run-time libraries, C", "CRT, release versions", "MSVCP71.dll", "LIBC.lib", "libraries [C++]", "libraries [C++], run-time", "linking [C++], libraries"] --- # C runtime (CRT) and C++ Standard Library (STL) `.lib` files diff --git a/docs/linux/connect-to-your-remote-linux-computer.md b/docs/linux/connect-to-your-remote-linux-computer.md index 814262fc004..1fa28147d5b 100644 --- a/docs/linux/connect-to-your-remote-linux-computer.md +++ b/docs/linux/connect-to-your-remote-linux-computer.md @@ -97,6 +97,17 @@ If ssh isn't already set up and running on your Linux system, follow these steps ::: moniker-end ::: moniker range="msvc-160" + +## Host key verification + +In Visual Studio version 16.10 or later, you will be asked to verify the host key fingerprint presented by the server when Visual Studio connects to a remote system for the first time. You may be familiar with this if you’ve used the OpenSSH command-line client or PuTTY before. The fingerprint identifies the server and is used to ensure that Visual Studio is connecting to the intended and trusted server. + +You will be asked to accept or deny the host key fingerprint presented by the server the first time a new remote connection is established, or anytime that a cached fingerprint has changed. You can also verify a fingerprint on demand by selecting a connection in the Connection Manager and clicking "Verify." + +If you are upgrading to Visual Studio 16.10 from an older version of Visual Studio, then all existing remote connections will be treated as a new connection. You will be prompted to accept the host key fingerprint before a connection is established and the accepted fingerprint will be cached. + +You can also update remote connections from ConnectionManager.exe using the `update` argument. + ## Supported SSH algorithms diff --git a/docs/linux/connectionmanager-reference.md b/docs/linux/connectionmanager-reference.md index bfe8d48e7e3..65d6d96bb9a 100644 --- a/docs/linux/connectionmanager-reference.md +++ b/docs/linux/connectionmanager-reference.md @@ -61,6 +61,10 @@ The functionality of ConnectionManager.exe is also available in Visual Studio. T - **`version`** Displays version information. + +- **`update`** \[*default* \| *all* \| *connection_id* \| *user\@host* \[**`--port`** *port*]] \[**`--previous`**] [**`--fingerprint`**] + + Added in Visual Studio 16.10. Updates the host key fingerprint of the specified connection(s). ### Options @@ -95,6 +99,14 @@ The functionality of ConnectionManager.exe is also available in Visual Studio. T - **`-i`** Same as **`--privatekey`**. + +- **`--previous`** + + Indicates that the connection(s) will be read from the previous version of connection manager, updated, and written to the new version. + +- **`--fingerprint`** + + The host key fingerprint presented by the server. Use this option with **`list`** to view a connection's fingerprint. ## Examples @@ -120,4 +132,4 @@ ConnectionManager.exe modify 21212121 --property shell=csh [Connect to your target Linux system in Visual Studio](connect-to-your-remote-linux-computer.md) -::: moniker-end \ No newline at end of file +::: moniker-end diff --git a/docs/standard-library/array-class-stl.md b/docs/standard-library/array-class-stl.md index 1943b85af28..0e8c6678d6b 100644 --- a/docs/standard-library/array-class-stl.md +++ b/docs/standard-library/array-class-stl.md @@ -6,7 +6,7 @@ f1_keywords: ["array/std::array", "array/std::array::const_iterator", "array/std helpviewer_keywords: ["std::array [C++]", "std::array [C++], const_iterator", "std::array [C++], const_pointer", "std::array [C++], const_reference", "std::array [C++], const_reverse_iterator", "std::array [C++], difference_type", "std::array [C++], iterator", "std::array [C++], pointer", "std::array [C++], reference", "std::array [C++], reverse_iterator", "std::array [C++], size_type", "std::array [C++], value_type", "std::array [C++], assign", "std::array [C++], at", "std::array [C++], back", "std::array [C++], begin", "std::array [C++], cbegin", "std::array [C++], cend", "std::array [C++], crbegin", "std::array [C++], crend", "std::array [C++], data", "std::array [C++], empty", "std::array [C++], end", "std::array [C++], fill", "std::array [C++], front", "std::array [C++], max_size", "std::array [C++], rbegin", "std::array [C++], rend", "std::array [C++], size", "std::array [C++], swap", ", ", "std::array [C++], const_iterator", "std::array [C++], const_pointer", "std::array [C++], const_reference", "std::array [C++], const_reverse_iterator", "std::array [C++], difference_type", "std::array [C++], iterator", "std::array [C++], pointer", "std::array [C++], reference", "std::array [C++], reverse_iterator", "std::array [C++], size_type", "std::array [C++], value_type", "std::array [C++], assign", "std::array [C++], at", "std::array [C++], back", "std::array [C++], begin", "std::array [C++], cbegin", "std::array [C++], cend", "std::array [C++], crbegin", "std::array [C++], crend", "std::array [C++], data", "std::array [C++], empty", "std::array [C++], end", "std::array [C++], fill", "std::array [C++], front", "std::array [C++], max_size", "std::array [C++], rbegin", "std::array [C++], rend", "std::array [C++], size", "std::array [C++], swap"] ms.assetid: fdfd43a5-b2b5-4b9e-991f-93bf10fb4293 --- -# array Class (C++ Standard Library) +# `array` Class (C++ Standard Library) Describes an object that controls a sequence of length `N` of elements of type `Ty`. The sequence is stored as an array of `Ty`, contained in the `array` object. @@ -29,44 +29,44 @@ The number of elements. |Type Definition|Description| |-|-| -|[const_iterator](#const_iterator)|The type of a constant iterator for the controlled sequence.| -|[const_pointer](#const_pointer)|The type of a constant pointer to an element.| -|[const_reference](#const_reference)|The type of a constant reference to an element.| -|[const_reverse_iterator](#const_reverse_iterator)|The type of a constant reverse iterator for the controlled sequence.| -|[difference_type](#difference_type)|The type of a signed distance between two elements.| -|[iterator](#iterator)|The type of an iterator for the controlled sequence.| -|[pointer](#pointer)|The type of a pointer to an element.| -|[reference](#reference)|The type of a reference to an element.| -|[reverse_iterator](#reverse_iterator)|The type of a reverse iterator for the controlled sequence.| -|[size_type](#size_type)|The type of an unsigned distance between two elements.| -|[value_type](#value_type)|The type of an element.| +|[`const_iterator`](#const_iterator)|The type of a constant iterator for the controlled sequence.| +|[`const_pointer`](#const_pointer)|The type of a constant pointer to an element.| +|[`const_reference`](#const_reference)|The type of a constant reference to an element.| +|[`const_reverse_iterator`](#const_reverse_iterator)|The type of a constant reverse iterator for the controlled sequence.| +|[`difference_type`](#difference_type)|The type of a signed distance between two elements.| +|[`iterator`](#iterator)|The type of an iterator for the controlled sequence.| +|[`pointer`](#pointer)|The type of a pointer to an element.| +|[`reference`](#reference)|The type of a reference to an element.| +|[`reverse_iterator`](#reverse_iterator)|The type of a reverse iterator for the controlled sequence.| +|[`size_type`](#size_type)|The type of an unsigned distance between two elements.| +|[`value_type`](#value_type)|The type of an element.| |Member Function|Description| |-|-| -|[array](#array)|Constructs an array object.| -|[assign](#assign)|(Obsolete. Use `fill`.) Replaces all elements.| -|[at](#at)|Accesses an element at a specified position.| -|[back](#back)|Accesses the last element.| -|[begin](#begin)|Designates the beginning of the controlled sequence.| -|[cbegin](#cbegin)|Returns a random-access const iterator to the first element in the array.| -|[cend](#cend)|Returns a random-access const iterator that points just beyond the end of the array.| -|[crbegin](#crbegin)|Returns a const iterator to the first element in a reversed array.| -|[crend](#crend)|Returns a const iterator to the end of a reversed array.| -|[data](#data)|Gets the address of the first element.| -|[empty](#empty)|Tests whether elements are present.| -|[end](#end)|Designates the end of the controlled sequence.| -|[fill](#fill)|Replaces all elements with a specified value.| -|[front](#front)|Accesses the first element.| -|[max_size](#max_size)|Counts the number of elements.| -|[rbegin](#rbegin)|Designates the beginning of the reversed controlled sequence.| -|[rend](#rend)|Designates the end of the reversed controlled sequence.| -|[size](#size)|Counts the number of elements.| -|[swap](#swap)|Swaps the contents of two containers.| +|[`array`](#array)|Constructs an array object.| +|[`assign`](#assign)|(Obsolete. Use `fill`.) Replaces all elements.| +|[`at`](#at)|Accesses an element at a specified position.| +|[`back`](#back)|Accesses the last element.| +|[`begin`](#begin)|Designates the beginning of the controlled sequence.| +|[`cbegin`](#cbegin)|Returns a random-access const iterator to the first element in the array.| +|[`cend`](#cend)|Returns a random-access const iterator that points just beyond the end of the array.| +|[`crbegin`](#crbegin)|Returns a const iterator to the first element in a reversed array.| +|[`crend`](#crend)|Returns a const iterator to the end of a reversed array.| +|[`data`](#data)|Gets the address of the first element.| +|[`empty`](#empty)|Tests whether elements are present.| +|[`end`](#end)|Designates the end of the controlled sequence.| +|[`fill`](#fill)|Replaces all elements with a specified value.| +|[`front`](#front)|Accesses the first element.| +|[`max_size`](#max_size)|Counts the number of elements.| +|[`rbegin`](#rbegin)|Designates the beginning of the reversed controlled sequence.| +|[`rend`](#rend)|Designates the end of the reversed controlled sequence.| +|[`size`](#size)|Counts the number of elements.| +|[`swap`](#swap)|Swaps the contents of two containers.| |Operator|Description| |-|-| -|[array::operator=](#op_eq)|Replaces the controlled sequence.| -|[array::operator\[\]](#op_at)|Accesses an element at a specified position.| +|[`array::operator=`](#op_eq)|Replaces the controlled sequence.| +|[`array::operator[]`](#op_at)|Accesses an element at a specified position.| ## Remarks @@ -80,11 +80,11 @@ creates the object `ai` that holds four integer values, initializes the first th ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` -## array::array +## `array::array` Constructs an array object. @@ -96,14 +96,14 @@ array(const array& right); ### Parameters -*right*\ +*`right`*\ Object or range to insert. ### Remarks The default constructor `array()` leaves the controlled sequence uninitialized (or default initialized). You use it to specify an uninitialized controlled sequence. -The copy constructor `array(const array& right)` initializes the controlled sequence with the sequence [*right*`.begin()`, *right*`.end()`). You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the array object *right*. +The copy constructor `array(const array& right)` initializes the controlled sequence with the sequence [*right*`.begin()`, *right*`.end()`). You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the array object *`right`*. ### Example @@ -143,11 +143,11 @@ int main() 0 1 2 3 ``` -## array::assign +## `array::assign` -Obsolete in C++11, replaced by [fill](#fill). Replaces all elements. +Obsolete in C++11, replaced by [`fill`](#fill). Replaces all elements. -## array::at +## `array::at` Accesses an element at a specified position. @@ -159,12 +159,12 @@ constexpr const_reference at(size_type off) const; ### Parameters -*off*\ +*`off`*\ Position of element to access. ### Remarks -The member functions return a reference to the element of the controlled sequence at position *off*. If that position is invalid, the function throws an object of class `out_of_range`. +The member functions return a reference to the element of the controlled sequence at position *`off`*. If that position is invalid, the function throws an object of class `out_of_range`. ### Example @@ -193,7 +193,7 @@ int main() } ``` -## array::back +## `array::back` Accesses the last element. @@ -238,7 +238,7 @@ int main() 3 ``` -## array::begin +## `array::begin` Designates the beginning of the controlled sequence. @@ -283,7 +283,7 @@ int main() 0 ``` -## array::cbegin +## `array::cbegin` Returns a **`const`** iterator that addresses the first element in the range. @@ -299,7 +299,7 @@ A **`const`** random-access iterator that points at the first element of the ran With the return value of `cbegin`, the elements in the range cannot be modified. -You can use this member function in place of the `begin()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [auto](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `begin()` and `cbegin()`. +You can use this member function in place of the `begin()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `begin()` and `cbegin()`. ```cpp auto i1 = Container.begin(); @@ -309,7 +309,7 @@ auto i2 = Container.cbegin(); // i2 is Container::const_iterator ``` -## array::cend +## `array::cend` Returns a **`const`** iterator that addresses the location just beyond the last element in a range. @@ -325,7 +325,7 @@ A random-access iterator that points just beyond the end of the range. `cend` is used to test whether an iterator has passed the end of its range. -You can use this member function in place of the `end()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [auto](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `end()` and `cend()`. +You can use this member function in place of the `end()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `end()` and `cend()`. ```cpp auto i1 = Container.end(); @@ -337,7 +337,7 @@ auto i2 = Container.cend(); The value returned by `cend` should not be dereferenced. -## array::const_iterator +## `array::const_iterator` The type of a constant iterator for the controlled sequence. @@ -385,7 +385,7 @@ it1: 0 1 2 3 it2: 0 ``` -## array::const_pointer +## `array::const_pointer` The type of a constant pointer to an element. @@ -429,7 +429,7 @@ int main() 0 ``` -## array::const_reference +## `array::const_reference` The type of a constant reference to an element. @@ -473,7 +473,7 @@ int main() 0 ``` -## array::const_reverse_iterator +## `array::const_reverse_iterator` The type of a constant reverse iterator for the controlled sequence. @@ -517,7 +517,7 @@ int main() 3 ``` -## array::crbegin +## `array::crbegin` Returns a const iterator to the first element in a reversed array. @@ -561,7 +561,7 @@ The first element of array is 1. The first element of the reversed array is 2. ``` -## array::crend +## `array::crend` Returns a const iterator that addresses the location succeeding the last element in a reversed array. @@ -575,7 +575,7 @@ A const reverse random-access iterator that addresses the location succeeding th ### Remarks -`crend` is used with a reversed array just as [array::cend](#cend) is used with a array. +`crend` is used with a reversed array just as [`array::cend`](#cend) is used with a array. With the return value of `crend` (suitably decremented), the array object cannot be modified. @@ -605,7 +605,7 @@ int main( ) 1 ``` -## array::data +## `array::data` Gets the address of the first element. @@ -651,7 +651,7 @@ int main() 0 ``` -## array::difference_type +## `array::difference_type` The type of a signed distance between two elements. @@ -695,7 +695,7 @@ int main() -4 ``` -## array::empty +## `array::empty` Tests whether no elements are present. @@ -745,7 +745,7 @@ false true ``` -## array::end +## `array::end` Designates the end of the controlled sequence. @@ -791,7 +791,7 @@ int main() 3 ``` -## array::fill +## `array::fill` Erases a array and copies the specified elements to the empty array. @@ -801,7 +801,7 @@ void fill(const Type& val); ### Parameters -*val*\ +*`val`*\ The value of the element being inserted into the array. ### Remarks @@ -836,7 +836,7 @@ int main() } ``` -## array::front +## `array::front` Accesses the first element. @@ -881,7 +881,7 @@ int main() 0 ``` -## array::iterator +## `array::iterator` The type of an iterator for the controlled sequence. @@ -930,7 +930,7 @@ it1: 0 1 2 3 it2: 0 ``` -## array::max_size +## `array::max_size` Counts the number of elements. @@ -973,7 +973,7 @@ int main() 4 ``` -## array::operator[] +## `array::operator[]` Accesses an element at a specified position. @@ -985,14 +985,14 @@ constexpr const_reference operator[](size_type off) const; ### Parameters -*off*\ +*`off`*\ Position of element to access. ### Remarks -The member functions return a reference to the element of the controlled sequence at position *off*. If that position is invalid, the behavior is undefined. +The member functions return a reference to the element of the controlled sequence at position *`off`*. If that position is invalid, the behavior is undefined. -There is also a non-member [get](array-functions.md#get) function available to get a reference to an element of an **array**. +There is also a non-member [`get`](array-functions.md#get) function available to get a reference to an element of an **`array`**. ### Example @@ -1026,7 +1026,7 @@ int main() 1 3 ``` -## array::operator= +## `array::operator=` Replaces the controlled sequence. @@ -1036,12 +1036,12 @@ array operator=(array right); ### Parameters -*right*\ +*`right`*\ Container to copy. ### Remarks -The member operator assigns each element of *right* to the corresponding element of the controlled sequence, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator assigns each element of *`right`* to the corresponding element of the controlled sequence, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -1081,7 +1081,7 @@ int main() 0 1 2 3 ``` -## array::pointer +## `array::pointer` The type of a pointer to an element. @@ -1125,7 +1125,7 @@ int main() 0 ``` -## array::rbegin +## `array::rbegin` Designates the beginning of the reversed controlled sequence. @@ -1170,7 +1170,7 @@ int main() 3 ``` -## array::reference +## `array::reference` The type of a reference to an element. @@ -1214,7 +1214,7 @@ int main() 0 ``` -## array::rend +## `array::rend` Designates the end of the reversed controlled sequence. @@ -1259,7 +1259,7 @@ int main() 0 ``` -## array::reverse_iterator +## `array::reverse_iterator` The type of a reverse iterator for the controlled sequence. @@ -1303,7 +1303,7 @@ int main() 3 ``` -## array::size +## `array::size` Counts the number of elements. @@ -1346,7 +1346,7 @@ int main() 4 ``` -## array::size_type +## `array::size_type` The type of an unsigned distance between two element. @@ -1390,7 +1390,7 @@ int main() 4 ``` -## array::swap +## `array::swap` Swaps the contents of this array with another array. @@ -1400,14 +1400,14 @@ void swap(array& right); ### Parameters -*right*\ +*`right`*\ Array to swap contents with. ### Remarks The member function swaps the controlled sequences between **`*this`** and *right*. It performs a number of element assignments and constructor calls proportional to `N`. -There is also a non-member [swap](array-functions.md#swap) function available to swap two **array** instances. +There is also a non-member [`swap`](array-functions.md#swap) function available to swap two **`array`** instances. ### Example @@ -1456,7 +1456,7 @@ int main() 0 1 2 3 ``` -## array::value_type +## `array::value_type` The type of an element. @@ -1505,4 +1505,4 @@ int main() ## See also -[\](../standard-library/array.md) +[``](../standard-library/array.md) diff --git a/docs/standard-library/file-system-navigation.md b/docs/standard-library/file-system-navigation.md index 7ccb02ec707..33204f7ad75 100644 --- a/docs/standard-library/file-system-navigation.md +++ b/docs/standard-library/file-system-navigation.md @@ -6,11 +6,11 @@ ms.assetid: f7cc5f5e-a541-4e00-87c7-a3769ef6096d --- # File System Navigation -The \ header implements the C++ File System Technical Specification ISO/IEC TS 18822:2015 (Final draft: [ISO/IEC JTC 1/SC 22/WG 21 N4100](https://wg21.link/n4100)) and has types and functions that enable you to write platform-independent code for navigating the file system. Because it's cross-platform, it contains APIs that aren't relevant for Windows systems. For example, `is_fifo(const path&)` always returns **`false`** on Windows. +The `` header implements the C++ File System Technical Specification ISO/IEC TS 18822:2015 (Final draft: [ISO/IEC JTC 1/SC 22/WG 21 N4100](https://wg21.link/n4100)) and has types and functions that enable you to write platform-independent code for navigating the file system. Because it's cross-platform, it contains APIs that aren't relevant for Windows systems. For example, `is_fifo(const path&)` always returns **`false`** on Windows. ## Overview -Use the \ APIs for the following tasks: +Use the `` APIs for the following tasks: - iterate over files and directories under a specified path @@ -28,7 +28,7 @@ For more information about File IO using the Standard Library, see [iostream Pro ### Constructing and composing paths -Paths in Windows (since XP) are stored natively in Unicode. The [path](../standard-library/path-class.md) class automatically does all necessary string conversions. It accepts arguments of both wide and narrow character arrays, and both `std::string` and `std::wstring` types formatted as UTF8 or UTF16. The `path` class also automatically normalizes path separators. You can use a single forward slash as a directory separator in constructor arguments. This separator lets you use the same strings to store paths in both Windows and UNIX environments: +Paths in Windows (since XP) are stored natively in Unicode. The [`path`](../standard-library/path-class.md) class automatically does all necessary string conversions. It accepts arguments of both wide and narrow character arrays, and both `std::string` and `std::wstring` types formatted as UTF8 or UTF16. The `path` class also automatically normalizes path separators. You can use a single forward slash as a directory separator in constructor arguments. This separator lets you use the same strings to store paths in both Windows and UNIX environments: ```cpp path pathToDisplay(L"/FileSystemTest/SubDir3"); // OK! @@ -149,7 +149,7 @@ To run this code, paste it into the full example above before `main` and uncomme ### Converting between path and string types -A `path` object is implicitly convertible to `std::wstring` or `std::string`. It means you can pass a path to functions such as [wofstream::open](../standard-library/basic-ofstream-class.md#open), as shown in this example: +A `path` object is implicitly convertible to `std::wstring` or `std::string`. It means you can pass a path to functions such as [`wofstream::open`](../standard-library/basic-ofstream-class.md#open), as shown in this example: ```cpp // filesystem_path_conversion.cpp @@ -202,6 +202,6 @@ Press Enter to exit ## Iterating directories and files -The \ header provides the [directory_iterator](../standard-library/directory-iterator-class.md) type to iterate over single directories, and the [recursive_directory_iterator](../standard-library/recursive-directory-iterator-class.md) class to iterate recursively over a directory and its subdirectories. After you construct an iterator by passing it a `path` object, the iterator points to the first directory_entry in the path. Create the end iterator by calling the default constructor. +The `` header provides the [`directory_iterator`](../standard-library/directory-iterator-class.md) type to iterate over single directories, and the [`recursive_directory_iterator`](../standard-library/recursive-directory-iterator-class.md) class to iterate recursively over a directory and its subdirectories. After you construct an iterator by passing it a `path` object, the iterator points to the first directory_entry in the path. Create the end iterator by calling the default constructor. -When iterating through a directory, there are several kinds of items you might discover. These items include directories, files, symbolic links, socket files, and others. The `directory_iterator` returns its items as [directory_entry](../standard-library/directory-entry-class.md) objects. +When iterating through a directory, there are several kinds of items you might discover. These items include directories, files, symbolic links, socket files, and others. The `directory_iterator` returns its items as [`directory_entry`](../standard-library/directory-entry-class.md) objects. diff --git a/docs/standard-library/function-objects-in-the-stl.md b/docs/standard-library/function-objects-in-the-stl.md index e023b51271e..e1055bf6f6d 100644 --- a/docs/standard-library/function-objects-in-the-stl.md +++ b/docs/standard-library/function-objects-in-the-stl.md @@ -38,7 +38,7 @@ The last line of the `main` function shows how you call the function object. Thi ## Function Objects and Containers -The C++ Standard Library contains several function objects in the [\](../standard-library/functional.md) header file. One use of these function objects is as a sorting criterion for containers. For example, the `set` container is declared as follows: +The C++ Standard Library contains several function objects in the [``](../standard-library/functional.md) header file. One use of these function objects is as a sorting criterion for containers. For example, the `set` container is declared as follows: ```cpp template ](../standard-library/functional.md) header for the argument `pred` or you can create your own. +The last argument to `remove_if` is a function object that returns a boolean value (a *predicate*). If the result of the function object is **`true`**, then the element is removed from the container being accessed by the iterators `first` and `last`. You can use any of the function objects declared in the [``](../standard-library/functional.md) header for the argument `pred` or you can create your own. ## See also diff --git a/docs/standard-library/memory-functions.md b/docs/standard-library/memory-functions.md index e6997d33265..d4034eda3d5 100644 --- a/docs/standard-library/memory-functions.md +++ b/docs/standard-library/memory-functions.md @@ -6,9 +6,9 @@ f1_keywords: ["memory/std::addressof", "memory/std::align", "memory/std::allocat ms.assetid: 3e1898c2-44b7-4626-87ce-84962e4c6f1a helpviewer_keywords: ["std::addressof [C++]", "std::align [C++]", "std::allocate_shared [C++]", "std::const_pointer_cast [C++]", "std::declare_no_pointers [C++]", "std::declare_reachable [C++]", "std::default_delete [C++]", "std::dynamic_pointer_cast [C++]", "std::get_deleter [C++]", "std::get_pointer_safety [C++]", "std::get_temporary_buffer [C++]", "std::make_shared [C++]", "std::make_unique [C++]", "std::owner_less [C++]", "std::return_temporary_buffer [C++]", "std::static_pointer_cast [C++]", "std::swap [C++]", "std::undeclare_no_pointers [C++]", "std::undeclare_reachable [C++]", "std::uninitialized_copy [C++]", "std::uninitialized_copy_n [C++]", "std::uninitialized_fill [C++]", "std::uninitialized_fill_n [C++]", "std::addressof [C++]", "std::align [C++]", "std::allocate_shared [C++]", "std::const_pointer_cast [C++]", "std::declare_no_pointers [C++]", "std::declare_reachable [C++]", "std::default_delete [C++]", "std::dynamic_pointer_cast [C++]", "std::get_deleter [C++]", "std::get_pointer_safety [C++]", "std::get_temporary_buffer [C++]", "std::make_shared [C++]", "std::make_unique [C++]", "std::owner_less [C++]", "std::return_temporary_buffer [C++]", "std::static_pointer_cast [C++]", "std::undeclare_no_pointers [C++]", "std::undeclare_reachable [C++]", "std::uninitialized_copy [C++]", "std::uninitialized_copy_n [C++]", "std::uninitialized_fill [C++]", "std::uninitialized_fill_n [C++]"] --- -# <memory> functions +# `` functions -## addressof +## `addressof` Gets the true address of an object. @@ -28,16 +28,16 @@ const T* addressof( ### Parameters -*value*\ +*`value`*\ The object or function for which to obtain the true address. ### Return Value -The actual address of the object or function referenced by *value*, even if an overloaded `operator&()` exists. +The actual address of the object or function referenced by *`value`*, even if an overloaded `operator&()` exists. ### Remarks -## align +## `align` Fits storage of the given size, aligned by the given alignment specification, into the first possible address of the given storage. @@ -52,27 +52,27 @@ void* align( ### Parameters -*alignment*\ +*`alignment`*\ The alignment bound to attempt. -*size*\ +*`size`*\ The size in bytes for the aligned storage. -*ptr*\ +*`ptr`*\ The starting address of the available contiguous storage pool to use. This parameter is also an output parameter, and is set to contain the new starting address if the alignment is successful. If `align()` is unsuccessful, this parameter isn't modified. -*space*\ +*`space`*\ The total space available to `align()` to use in creating the aligned storage. This parameter is also an output parameter, and contains the adjusted space left in the storage buffer after the aligned storage and any associated overhead is subtracted. If `align()` is unsuccessful, this parameter isn't modified. ### Return Value -A null pointer if the requested aligned buffer wouldn't fit into the available space; otherwise, the new value of *ptr*. +A `NULL` pointer if the requested aligned buffer wouldn't fit into the available space; otherwise, the new value of *`ptr`*. ### Remarks -The modified *ptr* and *space* parameters enable you to call `align()` repeatedly on the same buffer, possibly with different values for *alignment* and *size*. The following code snippet shows one use of `align()`. +The modified *`ptr`* and *`space`* parameters enable you to call `align()` repeatedly on the same buffer, possibly with different values for *`alignment`* and *`size`*. The following code snippet shows one use of `align()`. ```cpp #include // std::alignment_of() @@ -97,9 +97,9 @@ while (std::align(alignment, sizeof(MyObj), ptr, space)) { // possible to allow more aligned storage in this buffer. ``` -## allocate_shared +## `allocate_shared` -Creates a [shared_ptr](shared-ptr-class.md) to objects that are allocated and constructed for a given type by using a specified allocator. Returns the `shared_ptr`. +Creates a [`shared_ptr`](shared-ptr-class.md) to objects that are allocated and constructed for a given type by using a specified allocator. Returns the `shared_ptr`. ```cpp template @@ -110,17 +110,17 @@ shared_ptr allocate_shared( ### Parameters -*alloc*\ +*`alloc`*\ The allocator used to create objects. -*args*\ +*`args`*\ The zero or more arguments that become the objects. ### Remarks -The function creates the object `shared_ptr`, a pointer to `T(args...)` as allocated and constructed by *alloc*. +The function creates the object `shared_ptr`, a pointer to `T(args...)` as allocated and constructed by *`alloc`*. -## atomic_compare_exchange_strong +## `atomic_compare_exchange_strong` ```cpp template @@ -130,7 +130,7 @@ bool atomic_compare_exchange_strong( shared_ptr w); ``` -## atomic_compare_exchange_weak +## `atomic_compare_exchange_weak` ```cpp template @@ -140,7 +140,7 @@ bool atomic_compare_exchange_weak( shared_ptr w); ``` -## atomic_compare_exchange_strong_explicit +## `atomic_compare_exchange_strong_explicit` ```cpp template @@ -152,7 +152,7 @@ bool atomic_compare_exchange_strong_explicit( memory_order failure); ``` -## atomic_compare_exchange_weak_explicit +## `atomic_compare_exchange_weak_explicit` ```cpp template @@ -164,7 +164,7 @@ bool atomic_compare_exchange_weak_explicit( memory_order failure); ``` -## atomic_exchange +## `atomic_exchange` ```cpp template @@ -173,7 +173,7 @@ shared_ptr atomic_exchange( shared_ptr r); ``` -## atomic_exchange_explicit +## `atomic_exchange_explicit` ```cpp template @@ -183,7 +183,7 @@ shared_ptr atomic_exchange_explicit( memory_order mo); ``` -## atomic_is_lock_free +## `atomic_is_lock_free` ```cpp template @@ -191,7 +191,7 @@ bool atomic_is_lock_free( const shared_ptr* u); ``` -## atomic_load +## `atomic_load` ```cpp template @@ -199,7 +199,7 @@ shared_ptr atomic_load( const shared_ptr* u); ``` -## atomic_load_explicit +## `atomic_load_explicit` ```cpp template @@ -208,7 +208,7 @@ shared_ptr atomic_load_explicit( memory_order mo); ``` -## atomic_store +## `atomic_store` ```cpp template @@ -217,7 +217,7 @@ void atomic_store( shared_ptr r); ``` -## atomic_store_explicit +## `atomic_store_explicit` ```cpp template @@ -227,9 +227,9 @@ void atomic_store_explicit( memory_order mo); ``` -## const_pointer_cast +## `const_pointer_cast` -Const cast to [shared_ptr](shared-ptr-class.md). +Const cast to [`shared_ptr`](shared-ptr-class.md). ```cpp template @@ -243,18 +243,18 @@ shared_ptr const_pointer_cast( ### Parameters -*T*\ +*`T`*\ The type controlled by the returned shared pointer. -*Other*\ +*`Other`*\ The type controlled by the argument shared pointer. -*sp*\ +*`sp`*\ The argument shared pointer. ### Remarks -The template function returns an empty `shared_ptr` object if `const_cast(sp.get())` returns a null pointer; otherwise it returns a `shared_ptr` object that owns the resource that is owned by *sp*. The expression `const_cast(sp.get())` must be valid. +The template function returns an empty `shared_ptr` object if `const_cast(sp.get())` returns a null pointer; otherwise it returns a `shared_ptr` object that owns the resource that is owned by *`sp`*. The expression `const_cast(sp.get())` must be valid. ### Example @@ -281,7 +281,7 @@ int main() sp1 == 3 ``` -## declare_no_pointers +## `declare_no_pointers` Informs a garbage collector that the characters in the memory block defined by a base address pointer and block size contains no traceable pointers. @@ -293,17 +293,17 @@ void declare_no_pointers( ### Parameters -*ptr*\ +*`ptr`*\ Address of first character that no longer contains traceable pointers. -*size*\ -Size of block that starts at *ptr* that contains no traceable pointers. +*`size`*\ +Size of block that starts at *`ptr`* that contains no traceable pointers. ### Remarks -The function informs any garbage collector that the addresses in the range `[ ptr, ptr + size)` no longer contain traceable pointers. (Any pointers to allocated storage must not be dereferenced unless made reachable.) +The function informs any garbage collector that the addresses in the range `[ptr, ptr + size)` no longer contain traceable pointers. (Any pointers to allocated storage must not be dereferenced unless made reachable.) -## declare_reachable +## `declare_reachable` Informs garbage collection that the indicated address is to allocated storage and is reachable. @@ -314,16 +314,16 @@ void declare_reachable( ### Parameters -*ptr*\ +*`ptr`*\ A pointer to a reachable, allocated, valid storage area. ### Remarks -If *ptr* is not null, the function informs any garbage collector that *ptr* is now reachable, that is, it points to valid allocated storage. +If *`ptr`* is not null, the function informs any garbage collector that *`ptr`* is now reachable, that is, it points to valid allocated storage. -## default_delete +## `default_delete` -Deletes objects allocated with **operator new**. Suitable for use with [unique_ptr](unique-ptr-class.md). +Deletes objects allocated with **`operator new`**. Suitable for use with [`unique_ptr`](unique-ptr-class.md). ```cpp struct default_delete @@ -339,17 +339,17 @@ struct default_delete ### Parameters -*ptr*\ +*`ptr`*\ Pointer to the object to delete. -*Other*\ +*`Other`*\ The type of elements in the array to be deleted. ### Remarks -The class template describes a deleter that deletes scalar objects allocated with **operator new**, suitable for use with class template `unique_ptr`. It also has the explicit specialization `default_delete`. +The class template describes a deleter that deletes scalar objects allocated with **`operator new`**, suitable for use with class template `unique_ptr`. It also has the explicit specialization `default_delete`. -## destroy_at +## `destroy_at` ```cpp template @@ -359,7 +359,7 @@ void destroy_at( Same as `location->~T()`. -## destroy +## `destroy` ```cpp template @@ -375,7 +375,7 @@ for (; first != last; ++first) destroy_at(addressof(*first)); ``` -## destroy_n +## `destroy_n` ```cpp template @@ -392,9 +392,9 @@ for (; count > 0; (void)++first, --count) return first; ``` -## dynamic_pointer_cast +## `dynamic_pointer_cast` -Dynamic cast to [shared_ptr](shared-ptr-class.md). +Dynamic cast to [`shared_ptr`](shared-ptr-class.md). ```cpp template @@ -408,18 +408,18 @@ shared_ptr dynamic_pointer_cast( ### Parameters -*T*\ +*`T`*\ The type controlled by the returned shared pointer. -*Other*\ +*`Other`*\ The type controlled by the argument shared pointer. -*sp*\ +*`sp`*\ The argument shared pointer. ### Remarks -The template function returns an empty `shared_ptr` object if `dynamic_cast(sp.get())` returns a null pointer; otherwise it returns a `shared_ptr` object that owns the resource that is owned by *sp*. The expression `dynamic_cast(sp.get())` must be valid. +The template function returns an empty `shared_ptr` object if `dynamic_cast(sp.get())` returns a null pointer; otherwise it returns a `shared_ptr` object that owns the resource that is owned by *`sp`*. The expression `dynamic_cast(sp.get())` must be valid. ### Example @@ -457,9 +457,9 @@ int main() sp1->value == 3 ``` -## get_deleter +## `get_deleter` -Get the deleter from a [shared_ptr](shared-ptr-class.md). +Get the deleter from a [`shared_ptr`](shared-ptr-class.md). ```cpp template @@ -469,18 +469,18 @@ Deleter* get_deleter( ### Parameters -*Deleter*\ +*`Deleter`*\ The type of the deleter. -*T*\ +*`T`*\ The type controlled by the shared pointer. -*sp*\ +*`sp`*\ The shared pointer. ### Remarks -The template function returns a pointer to the deleter of type *Deleter* that belongs to the `shared_ptr` object *sp*. If *sp* has no deleter, or if its deleter is not of type *Deleter*, the function returns 0. +The template function returns a pointer to the deleter of type *`Deleter`* that belongs to the `shared_ptr` object *`sp`*. If *`sp`* has no deleter, or if its deleter is not of type *`Deleter`*, the function returns 0. ### Example @@ -526,7 +526,7 @@ get_deleter(sp0) != 0 == false get_deleter(sp1) != 0 == true ``` -## get_pointer_safety +## `get_pointer_safety` Returns the type of pointer safety assumed by any garbage collector. @@ -538,7 +538,7 @@ pointer_safety get_pointer_safety() noexcept; The function returns the type of pointer safety assumed by any automatic garbage collector. -## get_temporary_buffer +## `get_temporary_buffer` Allocates temporary storage for a sequence of elements that doesn't exceed a specified number of elements. @@ -596,9 +596,9 @@ The number of elements that the allocated memory could store is given by: resultPair.second = 9. ``` -## make_shared +## `make_shared` -Creates and returns a [shared_ptr](shared-ptr-class.md) that points to the allocated objects that are constructed from zero or more arguments by using the default allocator. Allocates and constructs both an object of the specified type and a `shared_ptr` to manage shared ownership of the object, and returns the `shared_ptr`. +Creates and returns a [`shared_ptr`](shared-ptr-class.md) that points to the allocated objects that are constructed from zero or more arguments by using the default allocator. Allocates and constructs both an object of the specified type and a `shared_ptr` to manage shared ownership of the object, and returns the `shared_ptr`. ```cpp template @@ -608,7 +608,7 @@ shared_ptr make_shared( ### Parameters -*args*\ +*`args`*\ Zero or more constructor arguments. The function infers which constructor overload to invoke based on the arguments that are provided. ### Remarks @@ -622,7 +622,7 @@ auto msp = std::make_shared(argument); However, the first statement makes two allocations, and if the allocation of the `shared_ptr` fails after the allocation of the `Example` object has succeeded, then the unnamed `Example` object is leaked. The statement that uses `make_shared` is simpler because there's only one function call involved. It's more efficient because the library can make a single allocation for both the object and the smart pointer. This function is both faster and leads to less memory fragmentation, and there's no chance of an exception on one allocation but not the other. Performance is improved by better locality for code that references the object and updates the reference counts in the smart pointer. -Consider using [make_unique](memory-functions.md#make_unique) if you don't need shared access to the object. Use [allocate_shared](memory-functions.md#allocate_shared) if you need to specify a custom allocator for the object. You can't use `make_shared` if your object requires a custom deleter, because there's no way to pass the deleter as an argument. +Consider using [`make_unique`](memory-functions.md#make_unique) if you don't need shared access to the object. Use [`allocate_shared`](memory-functions.md#allocate_shared) if you need to specify a custom allocator for the object. You can't use `make_shared` if your object requires a custom deleter, because there's no way to pass the deleter as an argument. The following example shows how to create shared pointers to a type by invoking specific constructor overloads. @@ -693,9 +693,9 @@ Playing Yesterday by The Beatles, use count: 3 Playing Blackbird by The Beatles, use count: 3 ``` -## make_unique +## `make_unique` -Creates and returns a [unique_ptr](unique-ptr-class.md) to an object of the specified type, which is constructed by using the specified arguments. +Creates and returns a [`unique_ptr`](unique-ptr-class.md) to an object of the specified type, which is constructed by using the specified arguments. ```cpp // make_unique @@ -713,24 +713,24 @@ template ### Parameters -*T*\ +*`T`*\ The type of the object that the `unique_ptr` will point to. -*Args*\ -The types of the constructor arguments specified by *args*. +*`Args`*\ +The types of the constructor arguments specified by *`args`*. -*args*\ -The arguments to be passed to the constructor of the object of type *T*. +*`args`*\ +The arguments to be passed to the constructor of the object of type *`T`*. -*elements*\ -An array of elements of type *T*. +*`elements`*\ +An array of elements of type *`T`*. -*size*\ +*`size`*\ The number of elements to allocate space for in the new array. ### Remarks -The first overload is used for single objects. The second overload is invoked for arrays. The third overload prevents you from specifying an array size in the type argument (make_unique\); this construction isn't supported by the current standard. When you use `make_unique` to create a `unique_ptr` to an array, you have to initialize the array elements separately. Rather than using this overload, perhaps a better choice is to use a [std::vector](vector-class.md). +The first overload is used for single objects. The second overload is invoked for arrays. The third overload prevents you from specifying an array size in the type argument (`make_unique`); this construction isn't supported by the current standard. When you use `make_unique` to create a `unique_ptr` to an array, you have to initialize the array elements separately. Rather than using this overload, perhaps a better choice is to use a [`std::vector`](vector-class.md). Because `make_unique` is carefully implemented for exception safety, we recommend that you use `make_unique` instead of directly calling `unique_ptr` constructors. @@ -742,7 +742,7 @@ The following example shows how to use `make_unique`. For more examples, see [Ho When you see error C2280 in connection with a `unique_ptr`, it is almost certainly because you are attempting to invoke its copy constructor, which is a deleted function. -## owner_less +## `owner_less` Allows ownership-based mixed comparisons of shared and weak pointers. Returns **`true`** if the left parameter is ordered before right parameter by the member function `owner_before`. @@ -807,17 +807,17 @@ template<> struct owner_less ### Parameters -*left*\ +*`left`*\ A shared or weak pointer. -*right*\ +*`right`*\ A shared or weak pointer. ### Remarks The class templates define all their member operators as returning `left.owner_before(right)`. -## reinterpret_pointer_cast +## `reinterpret_pointer_cast` Creates a new `shared_ptr` from an existing shared pointer by using a cast. @@ -833,16 +833,16 @@ shared_ptr reinterpret_pointer_cast( ### Parameters -*ptr*\ +*`ptr`*\ An reference to a `shared_ptr`. ### Remarks -If *ptr* is empty, the new `shared_ptr` is also empty, otherwise it shares ownership with *ptr*. The new shared pointer is the result of evaluating `reinterpret_cast(ptr.get())`, where `Y` is `typename std::shared_ptr::element_type`. The behavior is undefined if `reinterpret_cast((U*)nullptr)` is not well-formed. +If *`ptr`* is empty, the new `shared_ptr` is also empty, otherwise it shares ownership with *`ptr`*. The new shared pointer is the result of evaluating `reinterpret_cast(ptr.get())`, where `Y` is `typename std::shared_ptr::element_type`. The behavior is undefined if `reinterpret_cast((U*)nullptr)` is not well-formed. The template function that takes an lvalue reference is new in C++17. The template function that takes an rvalue reference is new in C++20. -## return_temporary_buffer +## `return_temporary_buffer` Deallocates the temporary memory that was allocated using the `get_temporary_buffer` template function. @@ -854,7 +854,7 @@ void return_temporary_buffer( ### Parameters -*buffer*\ +*`buffer`*\ A pointer to the memory to be deallocated. ### Remarks @@ -899,9 +899,9 @@ The number of elements that the allocated memory could store is given by: resultPair.second = 7. ``` -## static_pointer_cast +## `static_pointer_cast` -Static cast to [shared_ptr](shared-ptr-class.md). +Static cast to [`shared_ptr`](shared-ptr-class.md). ```cpp template @@ -915,18 +915,18 @@ shared_ptr static_pointer_cast( ### Parameters -*T*\ +*`T`*\ The type controlled by the returned shared pointer. -*Other*\ +*`Other`*\ The type controlled by the argument shared pointer. -*sp*\ +*`sp`*\ The argument shared pointer. ### Remarks -The template function returns an empty `shared_ptr` object if *sp* is an empty `shared_ptr` object; otherwise it returns a `shared_ptr` object that owns the resource that is owned by *sp*. The expression `static_cast(sp.get())` must be valid. +The template function returns an empty `shared_ptr` object if *`sp`* is an empty `shared_ptr` object; otherwise it returns a `shared_ptr` object that owns the resource that is owned by *`sp`*. The expression `static_cast(sp.get())` must be valid. ### Example @@ -963,9 +963,9 @@ int main() sp1->value == 3 ``` -## swap +## `swap` -Swap two [shared_ptr](shared-ptr-class.md), [unique_ptr](unique-ptr-class.md), or [weak_ptr](weak-ptr-class.md) objects. +Swap two [`shared_ptr`](shared-ptr-class.md), [`unique_ptr`](unique-ptr-class.md), or [`weak_ptr`](weak-ptr-class.md) objects. ```cpp template @@ -987,16 +987,16 @@ void swap( ### Parameters -*T*\ +*`T`*\ The type controlled by the argument pointer. -*Deleter*\ +*`Deleter`*\ The deleter of the unique pointer type. -*left*\ +*`left`*\ The left pointer. -*right*\ +*`right`*\ The right pointer. ### Remarks @@ -1048,7 +1048,7 @@ int main() *wp1 == 5 ``` -## undeclare_no_pointers +## `undeclare_no_pointers` Informs a garbage collector that the characters in the memory block defined by a base address pointer and block size may now contain traceable pointers. @@ -1060,17 +1060,17 @@ void undeclare_no_pointers( ### Parameters -*ptr*\ -A pointer to the memory address previously marked using [declare_no_pointers](#declare_no_pointers). +*`ptr`*\ +A pointer to the memory address previously marked using [`declare_no_pointers`](#declare_no_pointers). -*size*\ +*`size`*\ The number of bytes in the memory range. This value must equal the number used in the `declare_no_pointers` call. ### Remarks The function informs any garbage collector that the range of addresses `[ptr, ptr + size)` may now contain traceable pointers. -## undeclare_reachable +## `undeclare_reachable` Revokes a declaration of reachability for a specified memory location. @@ -1082,14 +1082,14 @@ T *undeclare_reachable( ### Parameters -*ptr*\ -A pointer to the memory address previously marked using [declare_reachable](#declare_reachable). +*`ptr`*\ +A pointer to the memory address previously marked using [`declare_reachable`](#declare_reachable). ### Remarks -If *ptr* is not **`nullptr`**, the function informs any garbage collector that *ptr* is no longer reachable. It returns a safely derived pointer that compares equal to *ptr*. +If *`ptr`* is not **`nullptr`**, the function informs any garbage collector that *`ptr`* is no longer reachable. It returns a safely derived pointer that compares equal to *`ptr`*. -## uninitialized_copy +## `uninitialized_copy` Copies objects from a specified source range into an uninitialized destination range. @@ -1110,16 +1110,16 @@ ForwardIterator uninitialized_copy( ### Parameters -*policy*\ +*`policy`*\ The execution policy to use. -*first*\ +*`first`*\ An input iterator addressing the first element in the source range. -*last*\ +*`last`*\ An input iterator addressing the last element in the source range. -*dest*\ +*`dest`*\ A forward iterator addressing the first element in the destination range. ### Return Value @@ -1209,7 +1209,7 @@ int main() } ``` -## uninitialized_copy_n +## `uninitialized_copy_n` Creates a copy of a specified number of elements from an input iterator. The copies are put in a forward iterator. @@ -1230,21 +1230,21 @@ ForwardIterator uninitialized_copy_n( ### Parameters -*policy*\ +*`policy`*\ The execution policy to use. -*first*\ +*`first`*\ An input iterator that refers to the object to copy. -*count*\ +*`count`*\ A signed or unsigned integer type specifying the number of times to copy the object. -*dest*\ +*`dest`*\ A forward iterator that refers to where the new copies go. ### Return Value -A forward iterator that addresses the first position beyond the destination. If the source range was empty, the iterator addresses *first*. +A forward iterator that addresses the first position beyond the destination. If the source range was empty, the iterator addresses *`first`*. ### Remarks @@ -1261,7 +1261,7 @@ unless the code throws an exception. In that case, all constructed objects are d The overload with an execution policy is new in C++17. -## uninitialized_default_construct +## `uninitialized_default_construct` Default constructs objects of the iterators' `value_type` in the specified range. @@ -1280,13 +1280,13 @@ void uninitialized_default_construct( ### Parameters -*policy*\ +*`policy`*\ The execution policy to use. -*first*\ +*`first`*\ An iterator addressing the first element in the range to construct. -*last*\ +*`last`*\ An iterator addressing one past the last element in the range to construct. ### Remarks @@ -1301,11 +1301,11 @@ for (; first != last; ++first) If an exception is thrown, previously constructed objects are destroyed in unspecified order. -The version with an execution policy has the same result, but executes according to the specified *policy*. +The version with an execution policy has the same result, but executes according to the specified *`policy`*. These functions are new in C++17. -## uninitialized_default_construct_n +## `uninitialized_default_construct_n` Default constructs a specified number of objects of the iterator's `value_type`, starting at the specified location. @@ -1324,13 +1324,13 @@ ForwardIterator uninitialized_default_construct_n( ### Parameters -*policy*\ +*`policy`*\ The execution policy to use. -*first*\ +*`first`*\ An iterator addressing the first element in the destination range to construct. -*count*\ +*`count`*\ The count of elements in the destination range to construct. ### Return Value @@ -1350,11 +1350,11 @@ return first; If an exception is thrown, previously constructed objects are destroyed in unspecified order. -The version with an execution policy has the same result, but executes according to the specified *policy*. +The version with an execution policy has the same result, but executes according to the specified *`policy`*. These functions are new in C++17. -## uninitialized_fill +## `uninitialized_fill` Copies objects of a specified value into an uninitialized destination range. @@ -1375,16 +1375,16 @@ void uninitialized_fill( ### Parameters -*policy*\ +*`policy`*\ The execution policy to use. -*first*\ +*`first`*\ A forward iterator addressing the first element in the destination range to initialize. -*last*\ +*`last`*\ A forward iterator addressing the last element in the destination range to initialize. -*value*\ +*`value`*\ The value to be used to initialize the destination range. ### Remarks @@ -1442,7 +1442,7 @@ int main() The initialized Array contains: 25 25 25 25 25 25 25 25 25 25 ``` -## uninitialized_fill_n +## `uninitialized_fill_n` Copies objects of a specified value into the specified number of elements of an uninitialized destination range. @@ -1463,16 +1463,16 @@ ForwardIterator uninitialized_fill_n( ### Parameters -*policy*\ +*`policy`*\ The execution policy to use. -*first*\ +*`first`*\ A forward iterator addressing the first element in the destination range to initialize. -*count*\ +*`count`*\ The number of elements to initialize. -*value*\ +*`value`*\ The value to use to initialize the destination range. ### Remarks @@ -1524,7 +1524,7 @@ int main() } ``` -## uninitialized_move +## `uninitialized_move` Moves elements from a source range to an uninitialized destination memory area. @@ -1545,16 +1545,16 @@ ForwardIterator uninitialized_move( ### Parameters -*policy*\ +*`policy`*\ The execution policy to use. -*first*\ +*`first`*\ An input iterator addressing the first element in the source range to move. -*last*\ +*`last`*\ An input iterator addressing one past the last element in the source range to move. -*dest*\ +*`dest`*\ The beginning of the destination range. ### Remarks @@ -1570,11 +1570,11 @@ return dest; If an exception is thrown, some objects in the source range might be left in a valid but unspecified state. Previously constructed objects are destroyed in unspecified order. -The version with an execution policy has the same result, but executes according to the specified *policy*. +The version with an execution policy has the same result, but executes according to the specified *`policy`*. These functions are new in C++17. -## uninitialized_move_n +## `uninitialized_move_n` Moves a specified number of elements from a source range to an uninitialized destination memory area. @@ -1595,16 +1595,16 @@ pair uninitialized_move_n( ### Parameters -*policy*\ +*`policy`*\ The execution policy to use. -*first*\ +*`first`*\ An input iterator addressing the first element in the source range to move. -*count*\ +*`count`*\ The count of elements in the source range to move. -*dest*\ +*`dest`*\ The beginning of the destination range. ### Remarks @@ -1620,11 +1620,11 @@ return {first, dest}; If an exception is thrown, some objects in the source range might be left in a valid but unspecified state. Previously constructed objects are destroyed in unspecified order. -The version with an execution policy has the same result, but executes according to the specified *policy*. +The version with an execution policy has the same result, but executes according to the specified *`policy`*. These functions are new in C++17. -## uninitialized_value_construct +## `uninitialized_value_construct` Constructs objects of the iterators' `value_type` by value initialization, in the specified range. @@ -1643,13 +1643,13 @@ void uninitialized_value_construct( ### Parameters -*policy*\ +*`policy`*\ The execution policy to use. -*first*\ +*`first`*\ An iterator addressing the first element in the range to value construct. -*last*\ +*`last`*\ An iterator addressing one past the last element in the range to value construct. ### Remarks @@ -1664,13 +1664,13 @@ for (; first != last; ++first) If an exception is thrown, previously constructed objects are destroyed in unspecified order. -The version with an execution policy has the same result, but executes according to the specified *policy*. +The version with an execution policy has the same result, but executes according to the specified *`policy`*. If a memory allocation failure occurs, a `std::bad_alloc` exception is thrown. These functions are new in C++17. -## uninitialized_value_construct_n +## `uninitialized_value_construct_n` Constructs a specified number of objects of the iterator's `value_type` by value initialization, starting at the specified location. @@ -1689,13 +1689,13 @@ ForwardIterator uninitialized_value_construct_n( ### Parameters -*policy*\ +*`policy`*\ The execution policy to use. -*first*\ +*`first`*\ An iterator addressing the first element in the destination range to construct. -*count*\ +*`count`*\ The count of elements in the destination range to construct. ### Remarks @@ -1711,13 +1711,13 @@ return first; If an exception is thrown, previously constructed objects are destroyed in unspecified order. -The version with an execution policy has the same result, but executes according to the specified *policy*. +The version with an execution policy has the same result, but executes according to the specified *`policy`*. If a memory allocation failure occurs, a `std::bad_alloc` exception is thrown. These functions are new in C++17. -## uses_allocator_v +## `uses_allocator_v` A helper variable template to access the value of the `uses_allocator` template. @@ -1728,4 +1728,4 @@ inline constexpr bool uses_allocator_v = uses_allocator::value; ## See also -[\](memory.md) +[``](memory.md) diff --git a/docs/standard-library/stl-containers.md b/docs/standard-library/stl-containers.md index 5b5dd55b96c..e682064b545 100644 --- a/docs/standard-library/stl-containers.md +++ b/docs/standard-library/stl-containers.md @@ -17,25 +17,25 @@ Containers can be divided into three categories: sequence containers, associativ Sequence containers maintain the ordering of inserted elements that you specify. -A `vector` container behaves like an array, but can automatically grow as required. It is random access and contiguously stored, and length is highly flexible. For these reasons and more, `vector` is the preferred sequence container for most applications. When in doubt as to what kind of sequence container to use, start by using a vector! For more information, see [vector Class](../standard-library/vector-class.md). +A `vector` container behaves like an array, but can automatically grow as required. It is random access and contiguously stored, and length is highly flexible. For these reasons and more, `vector` is the preferred sequence container for most applications. When in doubt as to what kind of sequence container to use, start by using a vector! For more information, see [`vector` Class](../standard-library/vector-class.md). -An `array` container has some of the strengths of `vector`, but the length isn't as flexible. For more information, see [array Class](../standard-library/array-class-stl.md). +An `array` container has some of the strengths of `vector`, but the length isn't as flexible. For more information, see [`array` Class](../standard-library/array-class-stl.md). -A `deque` (double-ended queue) container allows for fast insertions and deletions at the beginning and end of the container. It shares the random-access and flexible-length advantages of `vector`, but isn't contiguous. For more information, see [deque Class](../standard-library/deque-class.md). +A `deque` (double-ended queue) container allows for fast insertions and deletions at the beginning and end of the container. It shares the random-access and flexible-length advantages of `vector`, but isn't contiguous. For more information, see [`deque` Class](../standard-library/deque-class.md). -A `list` container is a doubly linked list that enables bidirectional access, fast insertions, and fast deletions anywhere in the container, but you can't randomly access an element in the container. For more information, see [list Class](../standard-library/list-class.md). +A `list` container is a doubly linked list that enables bidirectional access, fast insertions, and fast deletions anywhere in the container, but you can't randomly access an element in the container. For more information, see [`list` Class](../standard-library/list-class.md). -A `forward_list` container is a singly linked list—the forward-access version of `list`. For more information, see [forward_list Class](../standard-library/forward-list-class.md). +A `forward_list` container is a singly linked list—the forward-access version of `list`. For more information, see [`forward_list` Class](../standard-library/forward-list-class.md). ## Associative Containers In associative containers, elements are inserted in a pre-defined order—for example, as sorted ascending. Unordered associative containers are also available. The associative containers can be grouped into two subsets: maps and sets. -A `map`, sometimes referred to as a dictionary, consists of a key/value pair. The key is used to order the sequence, and the value is associated with that key. For example, a `map` might contain keys that represent every unique word in a text and corresponding values that represent the number of times that each word appears in the text. The unordered version of `map` is `unordered_map`. For more information, see [map Class](../standard-library/map-class.md) and [unordered_map Class](../standard-library/unordered-map-class.md). +A `map`, sometimes referred to as a dictionary, consists of a key/value pair. The key is used to order the sequence, and the value is associated with that key. For example, a `map` might contain keys that represent every unique word in a text and corresponding values that represent the number of times that each word appears in the text. The unordered version of `map` is `unordered_map`. For more information, see [`map` Class](../standard-library/map-class.md) and [`unordered_map` Class](../standard-library/unordered-map-class.md). -A `set` is just an ascending container of unique elements—the value is also the key. The unordered version of `set` is `unordered_set`. For more information, see [set Class](../standard-library/set-class.md) and [unordered_set Class](../standard-library/unordered-set-class.md). +A `set` is just an ascending container of unique elements—the value is also the key. The unordered version of `set` is `unordered_set`. For more information, see [`set` Class](../standard-library/set-class.md) and [`unordered_set` Class](../standard-library/unordered-set-class.md). -Both `map` and `set` only allow one instance of a key or element to be inserted into the container. If multiple instances of elements are required, use `multimap` or `multiset`. The unordered versions are `unordered_multimap` and `unordered_multiset`. For more information, see [multimap Class](../standard-library/multimap-class.md), [unordered_multimap Class](../standard-library/unordered-multimap-class.md), [multiset Class](../standard-library/multiset-class.md), and [unordered_multiset Class](../standard-library/unordered-multiset-class.md). +Both `map` and `set` only allow one instance of a key or element to be inserted into the container. If multiple instances of elements are required, use `multimap` or `multiset`. The unordered versions are `unordered_multimap` and `unordered_multiset`. For more information, see [`multimap` Class](../standard-library/multimap-class.md), [`unordered_multimap` Class](../standard-library/unordered-multimap-class.md), [`multiset` Class](../standard-library/multiset-class.md), and [`unordered_multiset` Class](../standard-library/unordered-multiset-class.md). Ordered maps and sets support bi-directional iterators, and their unordered counterparts support forward iterators. For more information, see [Iterators](../standard-library/iterators.md). @@ -128,11 +128,11 @@ The following member functions in map, multimap, set, and multiset have been ove A container adapter is a variation of a sequence or associative container that restricts the interface for simplicity and clarity. Container adapters don't support iterators. -A `queue` container follows FIFO (first in, first out) semantics. The first element *pushed*—that is, inserted into the queue—is the first to be *popped*—that is, removed from the queue. For more information, see [queue Class](../standard-library/queue-class.md). +A `queue` container follows FIFO (first in, first out) semantics. The first element *pushed*—that is, inserted into the queue—is the first to be *popped*—that is, removed from the queue. For more information, see [`queue` Class](../standard-library/queue-class.md). -A `priority_queue` container is organized such that the element that has the highest value is always first in the queue. For more information, see [priority_queue Class](../standard-library/priority-queue-class.md). +A `priority_queue` container is organized such that the element that has the highest value is always first in the queue. For more information, see [`priority_queue` Class](../standard-library/priority-queue-class.md). -A `stack` container follows LIFO (last in, first out) semantics. The last element pushed on the stack is the first element popped. For more information, see [stack Class](../standard-library/stack-class.md). +A `stack` container follows LIFO (last in, first out) semantics. The last element pushed on the stack is the first element popped. For more information, see [`stack` Class](../standard-library/stack-class.md). Because container adapters don't support iterators, they can't be used with the C++ Standard Library algorithms. For more information, see [Algorithms](../standard-library/algorithms.md). @@ -155,14 +155,14 @@ The elements of containers are accessed by using iterators. For more information ## Comparing containers -All containers overload the operator== for comparing two containers of the same type that have the same element type. You can use == to compare a vector\ to another vector\, but you can't use it to compare a vector\ to a list\ or a vector\ to a vector\. In C++98/03, you can use [std::equal](algorithm-functions.md#equal) or [std::mismatch](algorithm-functions.md#mismatch) to compare dissimilar container types and/or element types. In C++11, you can also use [std::is_permutation](algorithm-functions.md#is_permutation). But in all these cases the functions assume the containers are the same length. If the second range is shorter than the first, then undefined behavior results. If the second range is longer, results can still be incorrect because the comparison never continues past the end of the first range. +All containers overload the operator== for comparing two containers of the same type that have the same element type. You can use == to compare a vector\ to another vector\, but you can't use it to compare a vector\ to a list\ or a vector\ to a vector\. In C++98/03, you can use [`std::equal`](algorithm-functions.md#equal) or [`std::mismatch`](algorithm-functions.md#mismatch) to compare dissimilar container types and/or element types. In C++11, you can also use [`std::is_permutation`](algorithm-functions.md#is_permutation). But in all these cases the functions assume the containers are the same length. If the second range is shorter than the first, then undefined behavior results. If the second range is longer, results can still be incorrect because the comparison never continues past the end of the first range. ### Comparing dissimilar containers (C++14) -In C++14 and later, you can compare dissimilar containers and/or dissimilar elements types by using one of the `std::equal`, `std::mismatch`, or `std::is_permutation` function overloads that take two complete ranges. These overloads enable you to compare containers with different lengths. These overloads are much less susceptible to user error, and are optimized to return false in constant time when containers of dissimilar lengths are compared. Therefore, we recommend you use these overloads unless you have a clear reason not to, or you're using a [std::list](../standard-library/list-class.md) container, which does not benefit from the dual-range optimizations. +In C++14 and later, you can compare dissimilar containers and/or dissimilar elements types by using one of the `std::equal`, `std::mismatch`, or `std::is_permutation` function overloads that take two complete ranges. These overloads enable you to compare containers with different lengths. These overloads are much less susceptible to user error, and are optimized to return false in constant time when containers of dissimilar lengths are compared. Therefore, we recommend you use these overloads unless you have a clear reason not to, or you're using a [`std::list`](../standard-library/list-class.md) container, which does not benefit from the dual-range optimizations. ## See also [Parallel Containers](../parallel/concrt/parallel-containers-and-objects.md)\ -[\](../standard-library/sample-container.md)\ +[``](../standard-library/sample-container.md)\ [Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/string-functions.md b/docs/standard-library/string-functions.md index caf180d8f6e..cbff2a18a27 100644 --- a/docs/standard-library/string-functions.md +++ b/docs/standard-library/string-functions.md @@ -6,22 +6,22 @@ f1_keywords: ["string/std::getline", "string/std::stod", "string/std::stof", "st ms.assetid: 1a4ffd11-dce5-4cc6-a043-b95de034c7c4 helpviewer_keywords: ["std::getline [C++]", "std::stod [C++]", "std::stof [C++]", "std::stoi [C++]", "std::stol [C++]", "std::stold [C++]", "std::stoll [C++]", "std::stoul [C++]", "std::stoull [C++]", "std::swap [C++]", "std::to_string [C++]", "std::to_wstring [C++]"] --- -# <string> functions - -[getline](#getline)\ -[stod](#stod)\ -[stof](#stof)\ -[stoi](#stoi)\ -[stol](#stol)\ -[stold](#stold)\ -[stoll](#stoll)\ -[stoul](#stoul)\ -[stoull](#stoull)\ -[swap](#swap)\ -[to_string](#to_string)\ -[to_wstring](#to_wstring) - -## getline +# `` functions + +[`getline`](#getline)\ +[`stod`](#stod)\ +[`stof`](#stof)\ +[`stoi`](#stoi)\ +[`stol`](#stol)\ +[`stold`](#stold)\ +[`stoll`](#stoll)\ +[`stoul`](#stoul)\ +[`stoull`](#stoull)\ +[`swap`](#swap)\ +[`to_string`](#to_string)\ +[`to_wstring`](#to_wstring) + +## `getline` Extract strings from the input stream line-by-line. @@ -53,46 +53,46 @@ basic_istream& getline( ### Parameters -*in_stream*\ +*`in_stream`*\ The input stream from which a string is to be extracted. -*str*\ +*`str`*\ The string into which are read the characters from the input stream. -*delimiter*\ +*`delimiter`*\ The line delimiter. ### Return Value -The input stream *in_stream*. +The input stream *`in_stream`*. ### Remarks -The pair of function signatures marked `(1)` extract characters from *in_stream* until *delimiter* is found, storing them in *str*. +The pair of function signatures marked `(1)` extract characters from *`in_stream`* until *`delimiter`* is found, storing them in *`str`*. The pair of function signatures marked `(2)` use newline as the default line delimiter and behave as `getline(in_stream, str, in_stream. widen('\n'))`. -The second function of each pair is an analog to the first one to support [rvalue references](../cpp/lvalues-and-rvalues-visual-cpp.md). +The second function of each pair is an analog to the first one to support [`rvalue` references](../cpp/lvalues-and-rvalues-visual-cpp.md). Extraction stops when one of the following occurs: -- At end of file, in which case the internal state flag of *in_stream* is set to `ios_base::eofbit`. +- At end of file, in which case the internal state flag of *`in_stream`* is set to `ios_base::eofbit`. -- After the function extracts an element that compares equal to *delimiter*. The element doesn't get put back or appended to the controlled sequence. +- After the function extracts an element that compares equal to *`delimiter`*. The element doesn't get put back or appended to the controlled sequence. -- After the function extracts `str.`[max_size](../standard-library/basic-string-class.md#max_size) elements. The internal state flag of *in_stream* is set to `ios_base::failbit`. +- After the function extracts [`str.max_size`](../standard-library/basic-string-class.md#max_size) elements. The internal state flag of *`in_stream`* is set to `ios_base::failbit`. -- Some other error other than the ones previously listed; the internal state flag of *in_stream* is set to `ios_base::badbit`. +- Some other error other than the ones previously listed; the internal state flag of *`in_stream`* is set to `ios_base::badbit`. -For information about internal state flags, see [ios_base::iostate](../standard-library/ios-base-class.md#iostate). +For information about internal state flags, see [`ios_base::iostate`](../standard-library/ios-base-class.md#iostate). -If the function extracts no elements, the internal state flag of *in_stream* is set to `ios_base::failbit`. In any case, `getline` returns *in_stream*. +If the function extracts no elements, the internal state flag of *`in_stream`* is set to `ios_base::failbit`. In any case, `getline` returns *`in_stream`*. -If an exception is thrown, *in_stream* and *str* are left in a valid state. +If an exception is thrown, *`in_stream`* and *`str`* are left in a valid state. ### Example -The following code demonstrates `getline()` in two modes: first with the default delimiter (newline) and second with a whitespace as delimiter. The end-of-file character (CTRL-Z on the keyboard) is used to control termination of the while loops. This value sets the internal state flag of `cin` to `eofbit`, which must be cleared with [basic_ios::clear()](../standard-library/basic-ios-class.md#clear) before the second while loop will work properly. +The following code demonstrates `getline()` in two modes: first with the default delimiter (newline) and second with a whitespace as delimiter. The end-of-file character (CTRL-Z on the keyboard) is used to control termination of the while loops. This value sets the internal state flag of `cin` to `eofbit`, which must be cleared with [`basic_ios::clear()`](../standard-library/basic-ios-class.md#clear) before the second while loop will work properly. ```cpp // compile with: /EHsc /W4 @@ -133,7 +133,7 @@ int main() } ``` -## stod +## `stod` Converts a character sequence to a **`double`**. @@ -150,10 +150,10 @@ double stod( ### Parameters -*str*\ +*`str`*\ The character sequence to be converted. -*idx*\ +*`idx`*\ The index value of the first unconverted character. ### Return Value @@ -162,9 +162,9 @@ The **`double`** value. ### Remarks -The function converts the sequence of elements in *str* to a value of type **`double`** as if by calling `strtod( str.c_str(), _Eptr)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *idx* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. +The function converts the sequence of elements in *`str`* to a value of type **`double`** as if by calling `strtod( str.c_str(), _Eptr)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *`idx`* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. -## stof +## `stof` Converts a character sequence to a float. @@ -180,10 +180,10 @@ float stof( ### Parameters -*str*\ +*`str`*\ The character sequence to be converted. -*idx*\ +*`idx`*\ The index value of the first unconverted character. ### Return Value @@ -192,9 +192,9 @@ The **`float`** value. ### Remarks -The function converts the sequence of elements in *str* to a value of type **`float`** as if by calling `strtof( str.c_str(), _Eptr)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *idx* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. +The function converts the sequence of elements in *`str`* to a value of type **`float`** as if by calling `strtof( str.c_str(), _Eptr)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *`idx`* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. -## stoi +## `stoi` Converts a character sequence to an integer. @@ -216,24 +216,24 @@ The integer value. ### Parameters -*str*\ +*`str`*\ The character sequence to be converted. -*idx*\ +*`idx`*\ The index value of the first unconverted character. -*base*\ +*`base`*\ The number base to use. ### Remarks The function `stoi` converts the sequence of characters in *str* to a value of type **`int`** and returns the value. For example, when passed a character sequence "10", the value returned by `stoi` is the integer 10. -`stoi` behaves similarly to the function `strtol` for single-byte characters when it's called in the manner `strtol( str.c_str(), _Eptr, idx)`, where `_Eptr` is an object internal to the function; or `wcstol` for wide characters, when it's called in similar manner, `wcstol(Str.c_str(), _Eptr, idx)`. For more information, see [strtol, wcstol, _strtol_l, _wcstol_l](../c-runtime-library/reference/strtol-wcstol-strtol-l-wcstol-l.md). +`stoi` behaves similarly to the function `strtol` for single-byte characters when it's called in the manner `strtol( str.c_str(), _Eptr, idx)`, where `_Eptr` is an object internal to the function; or `wcstol` for wide characters, when it's called in similar manner, `wcstol(Str.c_str(), _Eptr, idx)`. For more information, see [`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](../c-runtime-library/reference/strtol-wcstol-strtol-l-wcstol-l.md). If `str.c_str() == *_Eptr`, `stoi` throws an object of type `invalid_argument`. If such a call would set `errno`, or if the returned value can't be represented as an object of type **`int`**, it throws an object of type `out_of_range`. Otherwise, if *idx* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx`. -## stol +## `stol` Converts a character sequence to a **`long`**. @@ -251,13 +251,13 @@ long stol( ### Parameters -*str*\ +*`str`*\ The character sequence to be converted. -*idx*\ +*`idx`*\ The index value of the first unconverted character. -*base*\ +*`base`*\ The number base to use. ### Return Value @@ -266,9 +266,9 @@ The long-integer value. ### Remarks -The function converts the sequence of elements in *str* to a value of type **`long`** as if by calling `strtol( str.c_str(), _Eptr, idx)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *idx* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. +The function converts the sequence of elements in *str* to a value of type **`long`** as if by calling `strtol( str.c_str(), _Eptr, idx)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *`idx`* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. -## stold +## `stold` Converts a character sequence to a **`long double`**. @@ -284,10 +284,10 @@ double stold( ### Parameters -*str*\ +*`str`*\ The character sequence to be converted. -*idx*\ +*`idx`*\ The index value of the first unconverted character. ### Return Value @@ -296,9 +296,9 @@ The **`long double`** value. ### Remarks -The function converts the sequence of elements in *str* to a value of type **`long double`** as if by calling `strtold( str.c_str(), _Eptr)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *idx* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. +The function converts the sequence of elements in *str* to a value of type **`long double`** as if by calling `strtold( str.c_str(), _Eptr)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *`idx`* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. -## stoll +## `stoll` Converts a character sequence to a **`long long`**. @@ -316,13 +316,13 @@ long long stoll( ### Parameters -*str*\ +*`str`*\ The character sequence to be converted. -*idx*\ +*`idx`*\ The index value of the first unconverted character. -*base*\ +*`base`*\ The number base to use. ### Return Value @@ -333,7 +333,7 @@ The **`long long`** value. The function converts the sequence of elements in *str* to a value of type **`long long`** as if by calling `strtoll( str.c_str(), _Eptr, idx)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *idx* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. -## stoul +## `stoul` Converts a character sequence to an unsigned long. @@ -351,13 +351,13 @@ unsigned long stoul( ### Parameters -*str*\ +*`str`*\ The character sequence to be converted. -*idx*\ +*`idx`*\ The index value of the first unconverted character. -*base*\ +*`base`*\ The number base to use. ### Return Value @@ -368,7 +368,7 @@ The unsigned long-integer value. The function converts the sequence of elements in *str* to a value of type **`unsigned long`** as if by calling `strtoul( str.c_str(), _Eptr, idx)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *idx* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. -## stoull +## `stoull` Converts a character sequence to an **`unsigned long long`**. @@ -386,13 +386,13 @@ unsigned long long stoull( ### Parameters -*str*\ +*`str`*\ The character sequence to be converted. -*idx*\ +*`idx`*\ The index value of the first unconverted character. -*base*\ +*`base`*\ The number base to use. ### Return Value @@ -401,9 +401,9 @@ The **`unsigned long long`** value. ### Remarks -The function converts the sequence of elements in *str* to a value of type **`unsigned long long`** as if by calling `strtoull( str.c_str(), _Eptr, idx)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *idx* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. +The function converts the sequence of elements in *str* to a value of type **`unsigned long long`** as if by calling `strtoull( str.c_str(), _Eptr, idx)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *`idx`* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. -## swap +## `swap` Exchanges the arrays of characters of two strings. @@ -414,15 +414,15 @@ void swap(basic_string& left, basic_string to_string +## `to_string` Converts a value to a `string`. @@ -477,7 +477,7 @@ string to_string(long double value); ### Parameters -*value*\ +*`value`*\ The value to be converted. ### Return Value @@ -488,25 +488,25 @@ The `string` that represents the value. The function converts *value* to a sequence of elements stored in an array object `Buf` internal to the function as if by calling `sprintf(Buf, Fmt, value)`, where `Fmt` is -- `"%d"` if *value* is of type **`int`** +- `"%d"` if *`value`* is of type **`int`** -- `"%u"` if *value* is of type **`unsigned int`** +- `"%u"` if *`value`* is of type **`unsigned int`** -- `"%ld"` if *value* is of type **`long`** +- `"%ld"` if *`value`* is of type **`long`** -- `"%lu"` if *value* is of type **`unsigned long`** +- `"%lu"` if *`value`* is of type **`unsigned long`** -- `"%lld"` if *value* is of type **`long long`** +- `"%lld"` if *`value`* is of type **`long long`** -- `"%llu"` if *value* is of type **`unsigned long long`** +- `"%llu"` if *`value`* is of type **`unsigned long long`** -- `"%f"` if *value* is of type **`float`** or **`double`** +- `"%f"` if *`value`* is of type **`float`** or **`double`** -- `"%Lf"` if *value* is of type **`long double`** +- `"%Lf"` if *`value`* is of type **`long double`** The function returns `string(Buf)`. -## to_wstring +## `to_wstring` Converts a value to a wide string. @@ -524,7 +524,7 @@ wstring to_wstring(long double value); ### Parameters -*value*\ +*`value`*\ The value to be converted. ### Return Value @@ -533,26 +533,26 @@ The wide string that represents the value. ### Remarks -The function converts *value* to a sequence of elements stored in an array object `Buf` internal to the function as if by calling `swprintf(Buf, Len, Fmt, value)`, where `Fmt` is +The function converts *`value`* to a sequence of elements stored in an array object `Buf` internal to the function as if by calling `swprintf(Buf, Len, Fmt, value)`, where `Fmt` is -- `L"%d"` if *value* is of type **`int`** +- `L"%d"` if *`value`* is of type **`int`** -- `L"%u"` if *value* is of type **`unsigned int`** +- `L"%u"` if *`value`* is of type **`unsigned int`** -- `L"%ld"` if *value* is of type **`long`** +- `L"%ld"` if *`value`* is of type **`long`** -- `L"%lu"` if *value* is of type **`unsigned long`** +- `L"%lu"` if *`value`* is of type **`unsigned long`** -- `L"%lld"` if *value* is of type **`long long`** +- `L"%lld"` if *`value`* is of type **`long long`** -- `L"%llu"` if *value* is of type **`unsigned long long`** +- `L"%llu"` if *`value`* is of type **`unsigned long long`** -- `L"%f"` if *value* is of type **`float`** or **`double`** +- `L"%f"` if *`value`* is of type **`float`** or **`double`** -- `L"%Lf"` if *value* is of type **`long double`** +- `L"%Lf"` if *`value`* is of type **`long double`** The function returns `wstring(Buf)`. ## See also -[\](../standard-library/string.md) +[``](../standard-library/string.md) diff --git a/docs/standard-library/string.md b/docs/standard-library/string.md index aeefac16e28..ae80df12b25 100644 --- a/docs/standard-library/string.md +++ b/docs/standard-library/string.md @@ -6,11 +6,11 @@ f1_keywords: [""] helpviewer_keywords: ["string header"] ms.assetid: a2fb9d00-d7ae-4170-bfea-2dc337aa37cf --- -# <string> +# `` Defines the container class template `basic_string` and various supporting templates. -For more information about `basic_string`, see [basic_string Class](../standard-library/basic-string-class.md) +For more information about `basic_string`, see [`basic_string` Class](../standard-library/basic-string-class.md) ## Syntax @@ -30,66 +30,66 @@ The C++ language and the C++ Standard Library support two types of strings: |Type name|Description| |-|-| -|[string](../standard-library/string-typedefs.md#string)|A type that describes a specialization of the class template `basic_string` with elements of type **`char`** as a `string`.| -|[wstring](../standard-library/string-typedefs.md#wstring)|A type that describes a specialization of the class template `basic_string` with elements of type **`wchar_t`** as a `wstring`.| -|[u16string](../standard-library/string-typedefs.md#u16string)|A type that describes a specialization of the class template `basic_string` based on elements of type **`char16_t`**.| -|[u32string](../standard-library/string-typedefs.md#u32string)|A type that describes a specialization of the class template `basic_string` based on elements of type **`char32_t`**.| +|[`string`](../standard-library/string-typedefs.md#string)|A type that describes a specialization of the class template `basic_string` with elements of type **`char`** as a `string`.| +|[`wstring`](../standard-library/string-typedefs.md#wstring)|A type that describes a specialization of the class template `basic_string` with elements of type **`wchar_t`** as a `wstring`.| +|[`u16string`](../standard-library/string-typedefs.md#u16string)|A type that describes a specialization of the class template `basic_string` based on elements of type **`char16_t`**.| +|[`u32string`](../standard-library/string-typedefs.md#u32string)|A type that describes a specialization of the class template `basic_string` based on elements of type **`char32_t`**.| ### Operators |Operator|Description| |-|-| -|[operator+](../standard-library/string-operators.md#op_add)|Concatenates two string objects.| -|[operator!=](../standard-library/string-operators.md#op_neq)|Tests if the string object on the left side of the operator is not equal to the string object on the right side.| -|[operator==](../standard-library/string-operators.md#op_eq_eq)|Tests if the string object on the left side of the operator is equal to the string object on the right side.| -|[operator<](../standard-library/string-operators.md#op_lt)|Tests if the string object on the left side of the operator is less than to the string object on the right side.| -|[operator<=](../standard-library/string-operators.md#op_lt_eq)|Tests if the string object on the left side of the operator is less than or equal to the string object on the right side.| -|[operator<\<](../standard-library/string-operators.md#op_lt_lt)|A template function that inserts a string into the output stream.| -|[operator>](../standard-library/string-operators.md#op_gt)|Tests if the string object on the left side of the operator is greater than to the string object on the right side.| -|[operator>=](../standard-library/string-operators.md#op_gt_eq)|Tests if the string object on the left side of the operator is greater than or equal to the string object on the right side.| -|[operator>>](../standard-library/string-operators.md#op_gt_gt)|A template function that extracts a string from the input stream.| +|[`operator+`](../standard-library/string-operators.md#op_add)|Concatenates two string objects.| +|[`operator!=`](../standard-library/string-operators.md#op_neq)|Tests if the string object on the left side of the operator is not equal to the string object on the right side.| +|[`operator==`](../standard-library/string-operators.md#op_eq_eq)|Tests if the string object on the left side of the operator is equal to the string object on the right side.| +|[`operator<`](../standard-library/string-operators.md#op_lt)|Tests if the string object on the left side of the operator is less than to the string object on the right side.| +|[`operator<=`](../standard-library/string-operators.md#op_lt_eq)|Tests if the string object on the left side of the operator is less than or equal to the string object on the right side.| +|[`operator<<`](../standard-library/string-operators.md#op_lt_lt)|A template function that inserts a string into the output stream.| +|[`operator>`](../standard-library/string-operators.md#op_gt)|Tests if the string object on the left side of the operator is greater than to the string object on the right side.| +|[`operator>=`](../standard-library/string-operators.md#op_gt_eq)|Tests if the string object on the left side of the operator is greater than or equal to the string object on the right side.| +|[`operator>>`](../standard-library/string-operators.md#op_gt_gt)|A template function that extracts a string from the input stream.| ### Specialized Template Functions |Name|Description| |-|-| |`hash`|Produces a hash of a string.| -|[swap](../standard-library/string-functions.md#swap)|Exchanges the arrays of characters of two strings.| -|[stod](../standard-library/string-functions.md#stod)|Converts a character sequence to a **`double`**.| -|[stof](../standard-library/string-functions.md#stof)|Converts a character sequence to a **`float`**.| -|[stoi](../standard-library/string-functions.md#stoi)|Converts a character sequence to an integer.| -|[stold](../standard-library/string-functions.md#stold)|Converts a character sequence to a **`long double`**.| -|[stoll](../standard-library/string-functions.md#stoll)|Converts a character sequence to a **`long long`**.| -|[stoul](../standard-library/string-functions.md#stoul)|Converts a character sequence to an **`unsigned long`**.| -|[stoull](../standard-library/string-functions.md#stoull)|Converts a character sequence to an **`unsigned long long`**.| -|[to_string](../standard-library/string-functions.md#to_string)|Converts a value to a `string`.| -|[to_wstring](../standard-library/string-functions.md#to_wstring)|Converts a value to a wide `string`.| +|[`swap`](../standard-library/string-functions.md#swap)|Exchanges the arrays of characters of two strings.| +|[`stod`](../standard-library/string-functions.md#stod)|Converts a character sequence to a **`double`**.| +|[`stof`](../standard-library/string-functions.md#stof)|Converts a character sequence to a **`float`**.| +|[`stoi`](../standard-library/string-functions.md#stoi)|Converts a character sequence to an **`int`**.| +|[`stold`](../standard-library/string-functions.md#stold)|Converts a character sequence to a **`long double`**.| +|[`stoll`](../standard-library/string-functions.md#stoll)|Converts a character sequence to a **`long long`**.| +|[`stoul`](../standard-library/string-functions.md#stoul)|Converts a character sequence to an **`unsigned long`**.| +|[`stoull`](../standard-library/string-functions.md#stoull)|Converts a character sequence to an **`unsigned long long`**.| +|[`to_string`](../standard-library/string-functions.md#to_string)|Converts a value to a `string`.| +|[`to_wstring`](../standard-library/string-functions.md#to_wstring)|Converts a value to a wide string.| ### Functions |Function|Description| |-|-| -|[getline Template](../standard-library/string-functions.md#getline)|Extract strings from the input stream line by line.| +|[`getline` Template](../standard-library/string-functions.md#getline)|Extract a `string`, line by line, from the input stream.| ### Classes |Class|Description| |-|-| -|[basic_string Class](../standard-library/basic-string-class.md)|A class template that describes objects that can store a sequence of arbitrary character-like objects.| -|[char_traits Struct](../standard-library/char-traits-struct.md)|A class template that describes attributes associated with a character of type CharType| +|[`basic_string` Class](../standard-library/basic-string-class.md)|A class template that describes objects that can store a sequence of arbitrary character-like objects.| +|[`char_traits` Struct](../standard-library/char-traits-struct.md)|A class template that describes attributes associated with a character of type `CharType`| ### Specializations |Name|Description| |-|-| -|[char_traits\ Struct](../standard-library/char-traits-char-struct.md)|A struct that is a specialization of the template struct `char_traits`\ to an element of type **`char`**.| -|[char_traits Struct](../standard-library/char-traits-wchar-t-struct.md)|A struct that is a specialization of the template struct `char_traits`\ to an element of type **`wchar_t`**.| -|[char_traits Struct](../standard-library/char-traits-char16-t-struct.md)|A struct that is a specialization of the template struct `char_traits`\ to an element of type **`char16_t`**.| -|[char_traits Struct](../standard-library/char-traits-char32-t-struct.md)|A struct that is a specialization of the template struct `char_traits`\ to an element of type **`char32_t`**.| +|[`char_traits` Struct](../standard-library/char-traits-char-struct.md)|A struct that is a specialization of the template struct `char_traits` to an element of type **`char`**.| +|[`char_traits` Struct](../standard-library/char-traits-wchar-t-struct.md)|A struct that is a specialization of the template struct `char_traits` to an element of type **`wchar_t`**.| +|[`char_traits` Struct](../standard-library/char-traits-char16-t-struct.md)|A struct that is a specialization of the template struct `char_traits` to an element of type **`char16_t`**.| +|[`char_traits` Struct](../standard-library/char-traits-char32-t-struct.md)|A struct that is a specialization of the template struct `char_traits` to an element of type **`char32_t`**.| ## Requirements -- **Header:** \ +- **Header:** `` - **Namespace:** std diff --git a/docs/standard-library/thread-safety-in-the-cpp-standard-library.md b/docs/standard-library/thread-safety-in-the-cpp-standard-library.md index 404e41673f9..cb0d8e69255 100644 --- a/docs/standard-library/thread-safety-in-the-cpp-standard-library.md +++ b/docs/standard-library/thread-safety-in-the-cpp-standard-library.md @@ -7,24 +7,24 @@ ms.assetid: 9351c8fb-4539-4728-b0e9-226e2ac4284b --- # Thread Safety in the C++ Standard Library -The following thread safety rules apply to all classes in the C++ Standard Library—this includes `shared_ptr`, as described below. Stronger guarantees are sometimes provided—for example, the standard iostream objects, as described below, and types specifically intended for multithreading, like those in [\](../standard-library/atomic.md). +The following thread safety rules apply to all classes in the C++ Standard Library—this includes `shared_ptr`, as described below. Stronger guarantees are sometimes provided—for example, the standard iostream objects, as described below, and types intended for multithreading, like those in [``](../standard-library/atomic.md). An object is thread-safe for reading from multiple threads. For example, given an object A, it is safe to read A from thread 1 and from thread 2 simultaneously. If an object is being written to by one thread, then all reads and writes to that object on the same or other threads must be protected. For example, given an object A, if thread 1 is writing to A, then thread 2 must be prevented from reading from or writing to A. -It is safe to read and write to one instance of a type even if another thread is reading or writing to a different instance of the same type. For example, given objects A and B of the same type, it is safe when A is being written in thread 1 and B is being read in thread 2. +It's safe to read and write to one instance of a type even if another thread is reading or writing to a different instance of the same type. For example, given objects A and B of the same type, it's safe when A is being written in thread 1 and B is being read in thread 2. ## shared_ptr -Multiple threads can simultaneously read and write different [shared_ptr](../standard-library/shared-ptr-class.md) objects, even when the objects are copies that share ownership. +Multiple threads can simultaneously read and write different [`shared_ptr`](../standard-library/shared-ptr-class.md) objects, even when the objects are copies that share ownership. ## iostream -The standard iostream objects `cin`, `cout`, `cerr`, `clog`, `wcin`, `wcout`, `wcerr`, and `wclog` follow the same rules as the other classes, with this exception: it is safe to write to an object from multiple threads. For example, thread 1 can write to [cout](../standard-library/iostream.md#cout) at the same time as thread 2. However, this can cause the output from the two threads to be intermixed. +The standard iostream objects `cin`, `cout`, `cerr`, `clog`, `wcin`, `wcout`, `wcerr`, and `wclog` follow the same rules as the other classes, with this exception: it's safe to write to an object from multiple threads. For example, thread 1 can write to [`cout`](../standard-library/iostream.md#cout) at the same time as thread 2. However, this can cause the output from the two threads to be intermixed. > [!NOTE] -> Reading from a stream buffer is not considered to be a read operation. Instead it is considered to be a write operation because the state of the class is changed. +> Reading from a stream buffer is not considered to be a read operation. Instead it's considered to be a write operation because the state of the class is changed. ## See also diff --git a/docs/standard-library/unique-ptr-class.md b/docs/standard-library/unique-ptr-class.md index 7d5750d6143..307826a119c 100644 --- a/docs/standard-library/unique-ptr-class.md +++ b/docs/standard-library/unique-ptr-class.md @@ -6,7 +6,7 @@ f1_keywords: ["memory/std::unique_ptr", "memory/std::unique_ptr::deleter_type", helpviewer_keywords: ["std::unique_ptr [C++]", "std::unique_ptr [C++], deleter_type", "std::unique_ptr [C++], element_type", "std::unique_ptr [C++], pointer", "std::unique_ptr [C++], get", "std::unique_ptr [C++], get_deleter", "std::unique_ptr [C++], release", "std::unique_ptr [C++], reset", "std::unique_ptr [C++], swap"] ms.assetid: acdf046b-831e-4a4a-83aa-6d4ee467db9a --- -# unique_ptr Class +# `unique_ptr` Class Stores a pointer to an owned object or array. The object/array is owned by no other `unique_ptr`. The object/array is destroyed when the `unique_ptr` is destroyed. @@ -70,16 +70,16 @@ public: ### Parameters -*Right*\ +*`Right`*\ A `unique_ptr`. -*Nptr*\ +*`Nptr`*\ An `rvalue` of type `std::nullptr_t`. -*Ptr*\ +*`Ptr`*\ A `pointer`. -*Deleter*\ +*`Deleter`*\ A `deleter` function that is bound to a `unique_ptr`. ## Exceptions @@ -90,11 +90,11 @@ No exceptions are generated by `unique_ptr`. The `unique_ptr` class supersedes `auto_ptr`, and can be used as an element of C++ Standard Library containers. -Use the [make_unique](../standard-library/memory-functions.md#make_unique) helper function to efficiently create new instances of `unique_ptr`. +Use the [`make_unique`](../standard-library/memory-functions.md#make_unique) helper function to efficiently create new instances of `unique_ptr`. -`unique_ptr` uniquely manages a resource. Each `unique_ptr` object stores a pointer to the object that it owns or stores a null pointer. A resource can be owned by no more than one `unique_ptr` object; when a `unique_ptr` object that owns a particular resource is destroyed, the resource is freed. A `unique_ptr` object may be moved, but not copied; for more information, see [Rvalue Reference Declarator: &&](../cpp/rvalue-reference-declarator-amp-amp.md). +`unique_ptr` uniquely manages a resource. Each `unique_ptr` object stores a pointer to the object that it owns or stores a null pointer. A resource can be owned by no more than one `unique_ptr` object; when a `unique_ptr` object that owns a particular resource is destroyed, the resource is freed. A `unique_ptr` object may be moved, but not copied; for more information, see [Rvalue Reference Declarator: `&&`](../cpp/rvalue-reference-declarator-amp-amp.md). -The resource is freed by calling a stored `deleter` object of type `Del` that knows how resources are allocated for a particular `unique_ptr`. The default `deleter` `default_delete` assumes that the resource pointed to by `ptr` is allocated with **`new`**, and that it can be freed by calling `delete _Ptr`. (A partial specialization `unique_ptr`manages array objects allocated with `new[]`, and has the default `deleter` `default_delete`, specialized to call delete[] `ptr`.) +The resource is freed by calling a stored `deleter` object of type `Del` that knows how resources are allocated for a particular `unique_ptr`. The default `deleter` `default_delete` assumes that the resource pointed to by `ptr` is allocated with **`new`**, and that it can be freed by calling `delete _Ptr`. (A partial specialization `unique_ptr`manages array objects allocated with `new[]`, and has the default `deleter` `default_delete`, specialized to call `delete[] ptr`.) The stored pointer to an owned resource, `stored_ptr` has type `pointer`. It is `Del::pointer` if defined, and `T *` if not. The stored `deleter` object `stored_deleter` occupies no space in the object if the `deleter` is stateless. Note that `Del` can be a reference type. @@ -104,36 +104,36 @@ The stored pointer to an owned resource, `stored_ptr` has type `pointer`. It is |Name|Description| |-|-| -|[unique_ptr](#unique_ptr)|There are seven constructors for `unique_ptr`.| +|[`unique_ptr`](#unique_ptr)|There are seven constructors for `unique_ptr`.| ### Typedefs |Name|Description| |-|-| -|[deleter_type](#deleter_type)|A synonym for the template parameter `Del`.| -|[element_type](#element_type)|A synonym for the template parameter `T`.| -|[pointer](#pointer)|A synonym for `Del::pointer` if defined, otherwise `T *`.| +|[`deleter_type`](#deleter_type)|A synonym for the template parameter `Del`.| +|[`element_type`](#element_type)|A synonym for the template parameter `T`.| +|[`pointer`](#pointer)|A synonym for `Del::pointer` if defined, otherwise `T *`.| ### Functions |Name|Description| |-|-| -|[get](#get)|Returns `stored_ptr`.| -|[get_deleter](#get_deleter)|Returns a reference to `stored_deleter`.| -|[release](#release)|stores `pointer()` in `stored_ptr` and returns its previous contents.| -|[reset](#reset)|Releases the currently owned resource and accepts a new resource.| -|[swap](#swap)|Exchanges resource and `deleter` with the provided `unique_ptr`.| +|[`get`](#get)|Returns `stored_ptr`.| +|[`get_deleter`](#get_deleter)|Returns a reference to `stored_deleter`.| +|[`release`](#release)|stores `pointer()` in `stored_ptr` and returns its previous contents.| +|[`reset`](#reset)|Releases the currently owned resource and accepts a new resource.| +|[`swap`](#swap)|Exchanges resource and `deleter` with the provided `unique_ptr`.| ### Operators |Name|Description| |-|-| -|**operator bool**|The operator returns a value of a type that is convertible to **`bool`**. The result of the conversion to **`bool`** is **`true`** when `get() != pointer()`, otherwise **`false`**.| +|**`operator bool`**|The operator returns a value of a type that is convertible to **`bool`**. The result of the conversion to **`bool`** is **`true`** when `get() != pointer()`, otherwise **`false`**.| |`operator->`|The member function returns `stored_ptr`.| |`operator*`|The member function returns `*stored_ptr`.| -|[operator=](#unique_ptr_operator_eq)|Assigns the value of a `unique_ptr` (or a `pointer-type`) to the current `unique_ptr`.| +|[`operator=`](#unique_ptr_operator_eq)|Assigns the value of a `unique_ptr` (or a `pointer-type`) to the current `unique_ptr`.| -### deleter_type +### `deleter_type` The type is a synonym for the template parameter `Del`. @@ -145,7 +145,7 @@ typedef Del deleter_type; The type is a synonym for the template parameter `Del`. -### element_type +### `element_type` The type is a synonym for the template parameter `Type`. @@ -157,7 +157,7 @@ typedef Type element_type; The type is a synonym for the template parameter `Ty`. -### get +### `get` Returns `stored_ptr`. @@ -169,7 +169,7 @@ pointer get() const; The member function returns `stored_ptr`. -### get_deleter +### `get_deleter` Returns a reference to `stored_deleter`. @@ -183,7 +183,7 @@ const Del& get_deleter() const; The member function returns a reference to `stored_deleter`. -### operator= +### `operator=` Assigns the address of the provided `unique_ptr` to the current one. @@ -202,7 +202,7 @@ A `unique_ptr` reference used to assign the value of to the current `unique_ptr` The member functions call `reset(right.release())` and move `right.stored_deleter` to `stored_deleter`, then return **`*this`**. -### pointer +### `pointer` A synonym for `Del::pointer` if defined, otherwise `Type *`. @@ -214,7 +214,7 @@ typedef T1 pointer; The type is a synonym for `Del::pointer` if defined, otherwise `Type *`. -### release +### `release` Releases ownership of the returned stored pointer to the caller and sets the stored pointer value to **`nullptr`**. @@ -274,7 +274,7 @@ Deleting Sample(42) Deleting Sample(3) ``` -### reset +### `reset` Takes ownership of the pointer parameter, and then deletes the original stored pointer. If the new pointer is the same as the original stored pointer, `reset` deletes the pointer and sets the stored pointer to **`nullptr`**. @@ -285,16 +285,16 @@ void reset(nullptr_t ptr); #### Parameters -*ptr*\ +*`ptr`*\ A pointer to the resource to take ownership of. #### Remarks -Use `reset` to change the stored [pointer](#pointer) owned by the `unique_ptr` to *ptr* and then delete the original stored pointer. If the `unique_ptr` was not empty, `reset` invokes the deleter function returned by [get_deleter](#get_deleter) on the original stored pointer. +Use `reset` to change the stored [`pointer`](#pointer) owned by the `unique_ptr` to *ptr* and then delete the original stored pointer. If the `unique_ptr` was not empty, `reset` invokes the deleter function returned by [`get_deleter`](#get_deleter) on the original stored pointer. -Because `reset` first stores the new pointer *ptr*, and then deletes the original stored pointer, it's possible for `reset` to immediately delete *ptr* if it is the same as the original stored pointer. +Because `reset` first stores the new pointer *`ptr`*, and then deletes the original stored pointer, it's possible for `reset` to immediately delete *`ptr`* if it is the same as the original stored pointer. -### swap +### `swap` Exchanges pointers between two `unique_ptr` objects. @@ -304,14 +304,14 @@ void swap(unique_ptr& right); #### Parameters -*right*\ +*`right`*\ A `unique_ptr` used to swap pointers. #### Remarks The member function swaps `stored_ptr` with `right.stored_ptr` and `stored_deleter` with `right.stored_deleter`. -### unique_ptr +### `unique_ptr` There are seven constructors for `unique_ptr`. @@ -336,22 +336,22 @@ template #### Parameters -*ptr*\ +*`ptr`*\ A pointer to the resource to be assigned to a `unique_ptr`. -*_Deleter*\ +*`_Deleter`*\ A `deleter` to be assigned to a `unique_ptr`. -*right*\ +*`right`*\ An `rvalue reference` to a `unique_ptr` from which `unique_ptr` fields are move assigned to the newly constructed `unique_ptr`. #### Remarks -The first two constructors construct an object that manages no resource. The third constructor stores *ptr* in `stored_ptr`. The fourth constructor stores *ptr* in `stored_ptr` and `deleter` in `stored_deleter`. +The first two constructors construct an object that manages no resource. The third constructor stores *ptr* in `stored_ptr`. The fourth constructor stores *`ptr`* in `stored_ptr` and `deleter` in `stored_deleter`. -The fifth constructor stores *ptr* in `stored_ptr` and moves `deleter` into `stored_deleter`. The sixth and seventh constructors store `right.release()` in `stored_ptr` and moves `right.get_deleter()` into `stored_deleter`. +The fifth constructor stores *`ptr`* in `stored_ptr` and moves `deleter` into `stored_deleter`. The sixth and seventh constructors store `right.release()` in `stored_ptr` and moves `right.get_deleter()` into `stored_deleter`. -### ~unique_ptr +### `~unique_ptr` The destructor for `unique_ptr`, destroys a `unique_ptr` object. diff --git a/docs/standard-library/using-insertion-operators-and-controlling-format.md b/docs/standard-library/using-insertion-operators-and-controlling-format.md index b15d633fdef..347fa139192 100644 --- a/docs/standard-library/using-insertion-operators-and-controlling-format.md +++ b/docs/standard-library/using-insertion-operators-and-controlling-format.md @@ -7,7 +7,7 @@ ms.assetid: cdefe986-6548-4cd1-8a67-b431d7d36a1c --- # Using Insertion Operators and Controlling Format -This topic shows how to control format and how to create insertion operators for your own classes. The insertion (**<<**) operator, which is preprogrammed for all standard C++ data types, sends bytes to an output stream object. Insertion operators work with predefined "manipulators," which are elements that change the default format of integer arguments. +This topic shows how to control format and how to create insertion operators for your own classes. The insertion (**`<<`**) operator, which is preprogrammed for all standard C++ data types, sends bytes to an output stream object. Insertion operators work with predefined "manipulators," which are elements that change the default format of integer arguments. You can control the format with the following options: @@ -88,7 +88,7 @@ int main( ) } ``` -The `width` member function is declared in \. If you use `setw` or any other manipulator with arguments, you must include \. In the output, strings are printed in a field of width 6 and integers in a field of width 10: +The `width` member function is declared in ``. If you use `setw` or any other manipulator with arguments, you must include ``. In the output, strings are printed in a field of width 6 and integers in a field of width 10: ```Output Zoot 1.23 @@ -120,11 +120,11 @@ Al 653.7 Stan 4358.24 ``` -The left-align flag is set by using the [setiosflags](../standard-library/iomanip-functions.md#setiosflags) manipulator with the `left` enumerator. This enumerator is defined in the [ios](../standard-library/basic-ios-class.md) class, so its reference must include the **ios::** prefix. The [resetiosflags](../standard-library/iomanip-functions.md#resetiosflags) manipulator turns off the left-align flag. Unlike `width` and `setw`, the effect of `setiosflags` and `resetiosflags` is permanent. +The left-align flag is set by using the [`setiosflags`](../standard-library/iomanip-functions.md#setiosflags) manipulator with the `left` enumerator. This enumerator is defined in the [`ios`](../standard-library/basic-ios-class.md) class, so its reference must include the **`ios::`** prefix. The [`resetiosflags`](../standard-library/iomanip-functions.md#resetiosflags) manipulator turns off the left-align flag. Unlike `width` and `setw`, the effect of `setiosflags` and `resetiosflags` is permanent. ## Precision -The default value for floating-point precision is six. For example, the number 3466.9768 prints as 3466.98. To change the way this value prints, use the [setprecision](../standard-library/iomanip-functions.md#setprecision) manipulator. The manipulator has two flags: [fixed](../standard-library/ios-functions.md#fixed) and [scientific](../standard-library/ios-functions.md#scientific). If [fixed](../standard-library/ios-functions.md#fixed) is set, the number prints as 3466.976800. If `scientific` is set, it prints as 3.4669773+003. +The default value for floating-point precision is six. For example, the number 3466.9768 prints as 3466.98. To change the way this value prints, use the [`setprecision`](../standard-library/iomanip-functions.md#setprecision) manipulator. The manipulator has two flags: [`fixed`](../standard-library/ios-functions.md#fixed) and [`scientific`](../standard-library/ios-functions.md#scientific). If [`fixed`](../standard-library/ios-functions.md#fixed) is set, the number prints as 3466.976800. If `scientific` is set, it prints as 3.4669773+003. To display the floating-point numbers shown in [Alignment](#vclrfalignmentanchor4) with one significant digit, replace the **`for`** loop as follows: @@ -177,11 +177,11 @@ Again, the program prints one digit after the decimal point. If either `ios::fix ## Radix -The `dec`, `oct`, and `hex` manipulators set the default radix for input and output. For example, if you insert the `hex` manipulator into the output stream, the object correctly translates the internal data representation of integers into a hexadecimal output format. The numbers are displayed with digits a through f in lower case if the [uppercase](../standard-library/ios-functions.md#uppercase) flag is clear (the default); otherwise, they are displayed in upper case. The default radix is `dec` (decimal). +The `dec`, `oct`, and `hex` manipulators set the default radix for input and output. For example, if you insert the `hex` manipulator into the output stream, the object correctly translates the internal data representation of integers into a hexadecimal output format. The numbers are displayed with digits a through f in lower case if the [`uppercase`](../standard-library/ios-functions.md#uppercase) flag is clear (the default); otherwise, they are displayed in upper case. The default radix is `dec` (decimal). ## Quoted strings (C++14) -When you insert a string into a stream, you can easily retrieve the same string back by calling the stringstream::str() member function. However, if you want to use the extraction operator to insert the stream into a new string at a later point, you may get an unexpected result because the >> operator by default will stop when it encounters the first whitespace character. +When you insert a string into a stream, you can easily retrieve the same string back by calling the `stringstream::str()` member function. However, if you want to use the extraction operator to insert the stream into a new string at a later point, you may get an unexpected result because the `>>` operator by default will stop when it encounters the first whitespace character. ```cpp std::stringstream ss; @@ -195,13 +195,13 @@ std::cout << inserted; // This is a sentence. std::cout << extracted; // This ``` -This behavior can be overcome manually, but to make string round-tripping more convenient, C++14 adds the `std::quoted` stream manipulator in \. Upon insertion, `quoted()` surrounds the string with a delimiter (double quote ' " ' by default) and upon extraction manipulates the stream to extract all characters until the final delimiter is encountered. Any embedded quotes are escaped with an escape character ('\\\\' by default). +This behavior can be overcome manually, but to make string round-tripping more convenient, C++14 adds the `std::quoted` stream manipulator in ``. Upon insertion, `quoted()` surrounds the string with a delimiter (double quote ' " ' by default) and upon extraction manipulates the stream to extract all characters until the final delimiter is encountered. Any embedded quotes are escaped with an escape character ('\\\\' by default). -The delimiters are present only in the stream object; they are not present in the extracted string but they are present in the string returned by [basic_stringstream::str](../standard-library/basic-stringstream-class.md#str). +The delimiters are present only in the stream object; they are not present in the extracted string but they are present in the string returned by [`basic_stringstream::str`](../standard-library/basic-stringstream-class.md#str). -The whitespace behavior of the insertion and extraction operations is independent of how a string is represented in code, so the quoted operator is useful regardless of whether the input string is a raw string literal or a regular string. The input string, whatever its format, can have embedded quotes, line breaks, tabs, and so on and all these will be preserved by the quoted() manipulator. +The whitespace behavior of the insertion and extraction operations is independent of how a string is represented in code, so the quoted operator is useful regardless of whether the input string is a raw string literal or a regular string. The input string, whatever its format, can have embedded quotes, line breaks, tabs, and so on and all these will be preserved by the `quoted()` manipulator. -For more information and full code examples, see [quoted](../standard-library/iomanip-functions.md#quoted). +For more information and full code examples, see [`quoted`](../standard-library/iomanip-functions.md#quoted). ## See also